Development OCC API reference

Version 0.1.0; OpenAPI 3.1.0.

This reference is generated from the checked-in OpenAPI contract. Run pnpm openapi:generate after changing an API route or schema; pnpm openapi:check verifies the generated contract, this reference, and the API cheat sheet.

The exported contract comes from the development-enabled OCC app, which is why the generated title is Development OCC API. Use POST /installation/bootstrap only for development or bootstrap flows that create the first Installation; production bootstraps through the Helm initialization Job before serving requests. After bootstrap, production uses the same authenticated controller resource operations through the selected Drivers and settings described in settings.

See authentication for supported credentials and their scope.

Table of contents

• Error responses
• Resources
• Operations
• Shared schemas

Error responses

Non-success JSON responses use the following envelope. Each operation lists its supported status codes. A NUL character or an unpaired UTF-16 surrogate in any request body string, object key or path parameter is refused with 400 INVALID_REQUEST. A JSON body with a value more than 24 levels below its root is refused with 400 INVALID_REQUEST and a TOO_DEEP detail before it is parsed, so that answer comes before any other body error. Operations that take a request body list 413 and 415. Any request whose declared body size exceeds the route's limit is refused with 413 PAYLOAD_TOO_LARGE, and any POST, PUT, PATCH or DELETE request with a body that is not JSON with 415 UNSUPPORTED_MEDIA_TYPE, even on an operation that takes no body. A query string sent to an operation that lists no query parameters is refused with 400 INVALID_REQUEST, except on the sign-in, sign-out, session and provider operations under /api/auth, which do not refuse one; most operations that take no body refuse a JSON body the same way. A detail path longer than 512 characters is cut to its leading whole segments (or the start of a long first key, keeping whole ~0 and ~1 escapes). When whole segments were dropped, a contract validation message says that the cut path contains the offending field. To fit the 256-character message cap, a message cuts long paths (ending them with …) and shows fewer problems before it cuts any problem wording; details keeps the paths.

Browse interactive examples in the API explorer.

Resources

Operations

Authentication

POST /api/auth/accounts

Create a local auth account as an Installation administrator

Operation ID: createAuthAccount

Permissions: Requires administer permission on the Installation. Creates a Better Auth account and an explicit IAM Principal in one transaction. Supplying roleId also creates a binding to that existing IAM Role; omitting roleId creates no grants. Public signup remains disabled.

Request body

Required: Yes

Content type: application/json

Example request

{  "email": "admin@example.com",  "name": "Documentation administrator",  "password": "replace-with-a-unique-password"}

Responses

201 response body: application/json

Example response

{  "data": {    "email": "admin@example.com",    "id": "user-docs-admin",    "name": "Documentation administrator",    "principalId": "principal-administrator"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

GET /api/auth/accounts/{userId}

Inspect current human account state

Operation ID: getAuthAccount

Permissions: Requires a current human Native IAM Installation administrator and trusted Origin. Returns guarded present state, not a receipt for any prior operation.

Parameters

Responses

200 response body: application/json

Example response

{  "data": {    "disabled": false,    "methods": [      {        "methodId": "method-password",        "providerId": "credential",        "subject": "user-docs-admin"      }    ],    "principalId": "principal-administrator",    "userId": "user-docs-admin",    "version": 1  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/accounts/{userId}/disable

Disable a human account

Operation ID: disableAuthAccount

Permissions: Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.

Parameters

Request body

Required: Yes

Content type: application/json

Example request

{  "expectedVersion": 1}

Responses

200 response body: application/json

Example response

{  "data": {    "userId": "user-docs-admin"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/accounts/{userId}/enable

Re-enable a disabled human account

Operation ID: enableAuthAccount

Permissions: Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.

Parameters

Request body

Required: Yes

Content type: application/json

Example request

{  "expectedVersion": 2}

Responses

200 response body: application/json

Example response

{  "data": {    "userId": "user-docs-admin"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/accounts/{userId}/enrol

Enrol an existing account that activation skipped

Operation ID: enrolAuthAccount

Permissions: Requires a current human Native IAM Installation administrator and trusted Origin. The account must already have its IAM Principal and exactly one password. Idempotent; enrolment grants no access beyond the account's existing IAM bindings.

Parameters

Responses

200 response body: application/json

Example response

{  "data": {    "created": true,    "principalId": "principal-administrator",    "userId": "user-docs-admin",    "version": 1  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/accounts/{userId}/methods/{methodId}/detach

Detach an external sign-in identity from an account

Operation ID: detachAuthMethod

Permissions: Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.

Parameters

Request body

Required: Yes

Content type: application/json

Example request

{  "expectedVersion": 1}

Responses

200 response body: application/json

Example response

{  "data": {    "userId": "user-docs-admin"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/accounts/{userId}/providers/google

Attach an exact Google identity to an existing account

Operation ID: attachGoogleIdentity

Permissions: Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.

Parameters

Request body

Required: Yes

Content type: application/json

Example request

{  "expectedVersion": 1,  "subject": "123456789012345678901"}

Responses

200 response body: application/json

Example response

{  "data": {    "userId": "user-docs-admin"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/accounts/{userId}/providers/oidc

Attach an exact OIDC identity to an existing account

Operation ID: attachOidcIdentity

Permissions: Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.

Parameters

Request body

Required: Yes

Content type: application/json

Example request

{  "expectedVersion": 1,  "subject": "provider-subject-docs-admin"}

Responses

200 response body: application/json

Example response

{  "data": {    "userId": "user-docs-admin"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/accounts/{userId}/revoke

Revoke all sessions for a human account

Operation ID: revokeAuthAccountSessions

Permissions: Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.

Parameters

Request body

Required: Yes

Content type: application/json

Example request

{  "expectedVersion": 1}

Responses

200 response body: application/json

Example response

{  "data": {    "userId": "user-docs-admin"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

GET /api/auth/providers

List configured browser sign-in methods

Operation ID: getAuthProviders

Permissions: List configured browser sign-in methods

Responses

200 response body: application/json

Example response

{  "data": {    "google": false,    "oidc": false,    "password": true,    "sessionBinding": false  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

GET /api/auth/providers/google/callback

Complete an enrolled Google sign-in

Operation ID: completeGoogleSignIn

Permissions: Consumes the browser-bound attempt before provider exchange. Redirects to Console after session and audit commit or with a fixed failure classification.

Responses

POST /api/auth/providers/google/result

Confirm which session a Google sign-in created

Operation ID: confirmGoogleSignIn

Permissions: Requires the configured browser Origin, the one-use login receipt cookie set by the callback, the matching attemptId and the session cookie that callback issued. Returns that session's sessionKey; never issues or extends a session.

Request body

Required: Yes

Content type: application/json

Example request

{  "attemptId": "example000000000000000000000000000000000000"}

Responses

200 response body: application/json

Example response

{  "data": {    "sessionKey": "example-session-binding-not-a-credential"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/providers/google/start

Start Google sign-in for an enrolled account

Operation ID: startGoogleSignIn

Permissions: Requires the exact configured browser Origin and, when Sec-Fetch-Site is present, same-origin. Creates a one-use browser-bound login attempt and returns its public attemptId for the result exchange; does not create an account or grant access.

Responses

200 response body: application/json

Example response

{  "data": {    "attemptId": "example000000000000000000000000000000000000",    "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=example&state=example-browser-bound-state"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

GET /api/auth/providers/oidc/callback

Complete an enrolled OIDC sign-in

Operation ID: completeOidcSignIn

Permissions: Consumes the browser-bound attempt before provider exchange. Redirects to Console after session and audit commit or with a fixed failure classification.

Responses

POST /api/auth/providers/oidc/result

Confirm which session an OIDC sign-in created

Operation ID: confirmOidcSignIn

Permissions: Requires the configured browser Origin, the one-use login receipt cookie set by the callback, the matching attemptId and the session cookie that callback issued. Returns that session's sessionKey; never issues or extends a session.

Request body

Required: Yes

Content type: application/json

Example request

{  "attemptId": "example000000000000000000000000000000000000"}

Responses

200 response body: application/json

Example response

{  "data": {    "sessionKey": "example-session-binding-not-a-credential"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/providers/oidc/start

Start OIDC sign-in for an enrolled account

Operation ID: startOidcSignIn

Permissions: Requires the exact configured browser Origin and, when Sec-Fetch-Site is present, same-origin. Creates a one-use browser-bound login attempt and returns its public attemptId for the result exchange; does not create an account or grant access.

Responses

200 response body: application/json

Example response

{  "data": {    "attemptId": "example000000000000000000000000000000000000",    "url": "https://identity.example.com/authorize?client_id=example&state=example-browser-bound-state"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

GET /api/auth/recovery

Inspect the recovery account designation

Operation ID: getAuthRecovery

Permissions: Requires a current human Native IAM Installation administrator and trusted Origin. Returns the present designation, whose password the database protects; not a receipt for any prior operation.

Responses

200 response body: application/json

Example response

{  "data": {    "methodId": "method-password",    "principalId": "principal-administrator",    "userId": "user-docs-admin"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/recovery

Move the recovery designation to another Installation administrator

Operation ID: replaceAuthRecovery

Permissions: Requires a current human Native IAM Installation administrator and trusted Origin who holds every IAM grant of the current holder's Principal (else 403). The target must be an enrolled, enabled account with one password whose Principal administers the Installation. expectedCurrentUserId comes from the recovery read and expectedVersion from the target's account read. Commits state and audit together; an unknown outcome must be inspected without automatic retry.

Request body

Required: Yes

Content type: application/json

Example request

{  "expectedCurrentUserId": "user-docs-admin",  "expectedVersion": 1,  "userId": "user-recovery-admin"}

Responses

200 response body: application/json

Example response

{  "data": {    "changed": true,    "methodId": "method-recovery-password",    "principalId": "principal-recovery-administrator",    "userId": "user-recovery-admin"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/service-keys

Issue a service API key

Operation ID: createServiceKey

Permissions: Requires a session or Installation-scoped service key with administer on the Installation. Issues a Better Auth key for an existing non-Agent ServicePrincipal in its exact scope when the caller already holds every IAM grant of that ServicePrincipal at the same or a broader scope; creates no identity or IAM grant. The plaintext key is returned only here.

Request body

Required: Yes

Content type: application/json

Example request

{  "expiresIn": 86400,  "name": "Documentation automation",  "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000",  "servicePrincipalId": "principal-docs-agent"}

Responses

201 response body: application/json

Example response

{  "data": {    "expiresAt": "2026-10-02T12:00:00.000Z",    "id": "key-docs-automation",    "key": "example-key-not-valid-for-authentication",    "name": "Documentation automation",    "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000",    "servicePrincipalId": "principal-docs-agent"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

DELETE /api/auth/service-keys/{keyId}

Revoke a service API key

Operation ID: revokeServiceKey

Permissions: Requires a session or Installation-scoped service key with administer on the Installation, plus every IAM grant of the key's ServicePrincipal, as for issuance. Deletes the stored Better Auth key; subsequent requests cannot authenticate with it.

Parameters

Responses

200 response body: application/json

Example response

{  "data": {    "id": "key-docs-automation",    "revoked": true  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

GET /api/auth/session

Inspect authentication without revealing session tokens

Operation ID: getAuthSession

Permissions: Returns authenticated status, public account identity, and a noncredential sessionKey that stays stable across reads and changes for a new session, or null without a valid session; session tokens and credentials are never returned.

Responses

200 response body: application/json

Example response

{  "data": null,  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/sign-in/email

Sign in with email and password

Operation ID: signInEmail

Permissions: Authenticates a local account and issues a user session cookie. In both profiles, repeated failed attempts for one email, or from one client address behind a trusted proxy, spend the password budget and may return 429 once it is spent. A successful sign-in also sets an HttpOnly known-device cookie; later attempts for that email from the same browser spend the browser's own budget instead of the email's. The cookie never authenticates. An email with a NUL character or an unpaired UTF-16 surrogate is refused with 400 INVALID_REQUEST and spends budget like a rejected password; the password is not checked for either.

Request body

Required: Yes

Content type: application/json

Example request

{  "email": "admin@example.com",  "password": "replace-with-a-unique-password"}

Responses

200 response body: application/json

Example response

{  "data": {    "authenticated": true  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /api/auth/sign-out

Sign out of the current session

Operation ID: signOut

Permissions: Revokes the current user session cookie.

Responses

200 response body: application/json

Example response

{  "data": {},  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

Backends

GET /backends

List configured Backends (experimental)

Operation ID: listBackends

Permissions: Requires administer permission on the requested Installation.

Responses

200 response body: application/json

Example response

{  "data": [],  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

Connections

GET /connection-templates

List all Installation-wide and Namespace-scoped connection templates

Operation ID: listConnectionTemplates

Permissions: Requires administer permission on the requested Installation.

Responses

200 response body: application/json

No readable resources

{  "data": [],  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

Example response

{  "data": [    {      "createdAt": "2026-10-01T12:00:00.000Z",      "current": {        "authorizationParameters": {},        "authorizationUrl": "https://accounts.example.com/authorize",        "createdAt": "2026-10-01T12:00:00.000Z",        "destinations": [          {            "host": "api.example.com",            "path": "/profile",            "port": 443          }        ],        "issuer": "https://accounts.example.com",        "mode": "manual",        "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000",        "scopes": [          "profile.read"        ],        "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000",        "tokenUrl": "https://accounts.example.com/token",        "version": 1      },      "displayName": "Example account",      "id": "ctp_123e4567-e89b-42d3-a456-426614174000",      "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000"    }  ],  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /connection-templates

Create an Installation-wide or Namespace-scoped connection template

Operation ID: createConnectionTemplate

Permissions: Requires administer permission on the requested Installation.

Request body

Required: Yes

Content type: application/json

Schema: object or object.

Example request

{  "authorizationUrl": "https://accounts.example.com/authorize",  "destinations": [    {      "host": "api.example.com",      "path": "/profile",      "port": 443    }  ],  "displayName": "Example account",  "issuer": "https://accounts.example.com",  "mode": "manual",  "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000",  "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000",  "scopes": [    "profile.read"  ],  "tokenUrl": "https://accounts.example.com/token"}

Responses

201 response body: application/json

Example response

{  "data": {    "createdAt": "2026-10-01T12:00:00.000Z",    "current": {      "authorizationParameters": {},      "authorizationUrl": "https://accounts.example.com/authorize",      "createdAt": "2026-10-01T12:00:00.000Z",      "destinations": [        {          "host": "api.example.com",          "path": "/profile",          "port": 443        }      ],      "issuer": "https://accounts.example.com",      "mode": "manual",      "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000",      "scopes": [        "profile.read"      ],      "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000",      "tokenUrl": "https://accounts.example.com/token",      "version": 1    },    "displayName": "Example account",    "id": "ctp_123e4567-e89b-42d3-a456-426614174000",    "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

POST /connection-templates/discover

Read public MCP resource and authorization server metadata

Operation ID: discoverConnectionTemplate

Permissions: Requires administer permission on the requested Installation.

Request body

Required: Yes

Content type: application/json

Example request

{  "serverUrl": "https://tools.example.com/mcp"}

Responses

200 response body: application/json

Example response

{  "data": {    "authorizationUrl": "https://accounts.example.com/authorize",    "issuer": "https://accounts.example.com",    "issuers": [      "https://accounts.example.com"    ],    "requestedScopes": [      "profile.read"    ],    "resource": "https://tools.example.com/mcp",    "resourceScopes": [      "profile.read"    ],    "serverUrl": "https://tools.example.com/mcp",    "tokenEndpointAuthMethods": [      "client_secret_basic"    ],    "tokenUrl": "https://accounts.example.com/token"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

DELETE /connection-templates/{connectionTemplateId}

Delete a connection template

Operation ID: deleteConnectionTemplate

Permissions: Requires administer permission on the requested Installation.

Parameters

Responses

GET /connection-templates/{connectionTemplateId}

Get one connection template

Operation ID: getConnectionTemplate

Permissions: Requires administer permission on the requested Installation.

Parameters

Responses

200 response body: application/json

Example response

{  "data": {    "createdAt": "2026-10-01T12:00:00.000Z",    "current": {      "authorizationParameters": {},      "authorizationUrl": "https://accounts.example.com/authorize",      "createdAt": "2026-10-01T12:00:00.000Z",      "destinations": [        {          "host": "api.example.com",          "path": "/profile",          "port": 443        }      ],      "issuer": "https://accounts.example.com",      "mode": "manual",      "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000",      "scopes": [        "profile.read"      ],      "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000",      "tokenUrl": "https://accounts.example.com/token",      "version": 1    },    "displayName": "Example account",    "id": "ctp_123e4567-e89b-42d3-a456-426614174000",    "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

PATCH /connection-templates/{connectionTemplateId}

Rename a connection template, or create a version with new approved values

Operation ID: updateConnectionTemplate

Permissions: Requires administer permission on the requested Installation.

Parameters

Request body

Required: Yes

Content type: application/json

Schema: object or object or object.

Example request

{  "displayName": "Engineering account"}

Responses

200 response body: application/json

Example response

{  "data": {    "createdAt": "2026-10-01T12:00:00.000Z",    "current": {      "authorizationParameters": {},      "authorizationUrl": "https://accounts.example.com/authorize",      "createdAt": "2026-10-01T12:00:00.000Z",      "destinations": [        {          "host": "api.example.com",          "path": "/profile",          "port": 443        }      ],      "issuer": "https://accounts.example.com",      "mode": "manual",      "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000",      "scopes": [        "profile.read"      ],      "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000",      "tokenUrl": "https://accounts.example.com/token",      "version": 1    },    "displayName": "Engineering account",    "id": "ctp_123e4567-e89b-42d3-a456-426614174000",    "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000"  },  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}

GET /namespaces/{namespaceId}/connection-templates

List connection templates the caller may connect in this Namespace

Operation ID: listUsableConnectionTemplates

Permissions: Requires create permission for CredentialSource resources in the requested Namespace.

Parameters

Responses

200 response body: application/json

No readable resources

{  "data": [],  "meta": {    "requestId": "req_123e4567-e89b-42d3-a456-426614174000"  }}