Endpoints: Core & Sessions
Health
Section titled “Health”Both probes are public: an orchestrator calls them without credentials.
GET /health
Section titled “GET /health”Liveness probe
Public. The process is up and serving. It checks nothing else, so a database outage never causes a healthy instance to restart.
Response 200 (application/json)
{ "status": "ok"}GET /health/ready
Section titled “GET /health/ready”Readiness probe — storage reachable
Public. The process is up and storage answers a ping. Point load balancers and the Kubernetes readinessProbe here so traffic moves away while the database is unreachable.
Response 200 (application/json)
{ "status": "ok", "storage": "ok"}503— Storage did not answer:{"status": "unavailable", "storage": "unreachable"}
Capabilities
Section titled “Capabilities”What this deployment has mounted, so a client offers only what exists.
GET /v1/capabilities
Section titled “GET /v1/capabilities”Which domains are mounted on this deployment
Any authenticated principal. Returns the installed domains — always at least platform, plus whatever product is mounted on it — the deployment mode, whether this deployment sends email, and which audit sink transports it allows. Use it to avoid offering functionality this deployment does not have; it is not an authorization check, and says nothing about what the caller’s organization may do.
Response 200 (application/json)
{ "capabilities": [ { "name": "string", "title": "string", "description": "string", "version": "string" } ], "deployment": { "mode": "self_hosted" }, "mail": { "delivers": true }, "audit_push": { "https": true, "syslog": true }}Authentication
Section titled “Authentication”API keys (service accounts), a person’s access tokens for agents and scripts, account recovery and email verification, and the permission catalogue. An API key is the machine-to-machine credential for CI and MCP clients; it is passed in the X-API-Key header. An access token acts as the person who created it: the access-token routes need a signed-in session, and an API key or an access token gets 403 there.
POST /v1/auth/password/forgot
Section titled “POST /v1/auth/password/forgot”Email a password-reset link
Public. Emails a password-reset link, valid for 30 minutes, to an active account that signs in with a password. Always 202 with the same message, so the response never tells a caller whether an address has an account. Every call spends from the caller’s per-IP budget.
Request body (application/json)
{}Response 202 (application/json)
{ "detail": "string"}429— Too Many Requests
POST /v1/auth/password/reset
Section titled “POST /v1/auth/password/reset”Choose a new password with a reset link
Public: the token is the credential. Sets the password, signs the account out of every session and, since following the link proves control of the address, marks the email verified. The caller then signs in normally. The token is single-use; an invalid one spends from the per-IP budget.
Request body (application/json)
{ "token": "string", "new_password": "string"}Response 200 (application/json) — Password changed
{ "detail": "string"}400— Token unknown, already used or expired429— Too Many Requests
POST /v1/auth/email/verify
Section titled “POST /v1/auth/email/verify”Confirm an email address with a verification link
Public: the token is the credential. Confirms an email address with a verification link’s token. The token is single-use and valid for 2 days. Same 400 and budget rules as POST /auth/password/reset.
Request body (application/json)
{ "token": "string"}Response 200 (application/json)
{ "detail": "string"}400— Token unknown, already used or expired429— Too Many Requests
POST /v1/auth/email/verify/resend
Section titled “POST /v1/auth/email/verify/resend”Send the signed-in account a new verification link
Sends the signed-in account a new verification link and retires the earlier one. Returns 202 and does nothing for an account already verified. Requires a human session: an API key has no address to verify.
Response 202 (application/json)
{ "detail": "string"}400— Bad Request401— Unauthorized429— Too Many Requests
GET /v1/auth/keys
Section titled “GET /v1/auth/keys”List service accounts in the caller’s organization
Every service account of the caller’s organization. The raw key and its hash are never returned. Requires api_keys:manage (admin by default).
last_refused_ip and last_refused_at show the newest address ip_allowlist refused, within retention.network_events_days.
Response 200 (application/json)
{ "keys": [ { "key_id": "string", "role": "string", "name": "string", "ip_allowlist": [ "string" ], "scopes": [ "string" ], "created_at": "2026-01-01T00:00:00Z", "is_active": true, "last_refused_ip": "string", "last_refused_at": "2026-01-01T00:00:00Z" } ]}401— Unauthorized403— Forbidden
POST /v1/auth/keys
Section titled “POST /v1/auth/keys”Create a new service account
Creates a service account: a named API key with a role, scoped to the caller’s organization. Requires api_keys:manage (admin by default), and the caller must hold every permission the role grants.
The raw key is returned once in this response and never stored. If you lose it, revoke the key and create a new one.
role is a built-in role or one of the org’s custom roles (custom:<slug>). scopes, if set, narrow the key to those of the role’s permissions.
ip_allowlist, if set, restricts the source addresses the key works from. A request from outside it gets 403, not 401: the key is valid, just not usable from there. The caller’s address is the connecting address or, behind a proxy listed in network.trusted_proxies, the first X-Forwarded-For hop that proxy added. A hop the client wrote itself is never read.
In the dashboard: Organization → Access → Service Accounts.
Request body (application/json)
{ "role": "pipeline", "name": "string", "ip_allowlist": [ "string" ], "scopes": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
role | string | no | A built-in role or custom:<slug>. Defaults to pipeline: the narrowest role that runs the product’s workflow. |
name | string | null | no | A label for people reading the key list. |
ip_allowlist | string[] | null | no | Source addresses the key works from: bare IPs (203.0.113.5, a /32) or CIDR blocks (203.0.113.0/24). A malformed entry rejects the request with 422. None: usable from anywhere. |
scopes | string[] | null | no | Narrows the key to these permissions of its role — never more than the role holds. None: everything the role holds. |
Response 201 (application/json) — Key created; save key now, it is never shown again
{ "key_id": "string", "key": "string", "role": "string", "name": "string", "ip_allowlist": [ "string" ], "scopes": [ "string" ], "created_at": "2026-01-01T00:00:00Z"}401— Unauthorized403— The caller lacksapi_keys:manage, or a permission the role grants
DELETE /v1/auth/keys/{key_id}
Section titled “DELETE /v1/auth/keys/{key_id}”Revoke a service account
Deactivates the service account key_id of the caller’s organization. A revoked key is rejected from its next request on. Requires api_keys:manage (admin by default).
In the dashboard: Organization → Access → Service Accounts, the row’s delete action.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
key_id | string | yes | Key ID returned at creation |
Response 200 (application/json) — Key revoked
{ "detail": "Key 3f4a5b6c-... revoked"}401— Unauthorized403— Forbidden404— No such key in this organization
GET /v1/permissions
Section titled “GET /v1/permissions”Every permission declared on this deployment
Every permission the platform and the mounted products declare. Each entry gives default_role, the lowest role on the viewer-to-owner ladder that holds it; read_only, whether the auditor role holds it; and pipeline, whether the pipeline role holds it. Any authenticated principal may call it.
Response 200 (application/json)
{ "permissions": [ { "name": "string", "description": "string", "default_role": "owner", "read_only": true, "pipeline": true } ]}GET /v1/auth/me/access-tokens
Section titled “GET /v1/auth/me/access-tokens”List your access tokens
The caller’s access tokens, newest first, without the raw value. Requires a signed-in session.
Response 200 (application/json)
{ "tokens": [ { "token_id": "string", "name": "string", "scope": "read", "org_id": "string", "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T00:00:00Z" } ]}401— Unauthorized403— Forbidden
POST /v1/auth/me/access-tokens
Section titled “POST /v1/auth/me/access-tokens”Create an access token
Creates a person’s credential for an agent or a script. The token acts as you, never with more than your role in the org it acts in, and capped by its scope. The raw token (ot_pat_…) is returned once. Requires a signed-in session: an API key or an access token gets 403.
Request body (application/json)
{ "name": "string", "scope": "read", "org_id": "string", "expires_in_days": 1}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | What the token is for, e.g. ‘Claude Code’. |
scope | "read" | "write" | "admin" | null | no | read: read-only permissions. write: also the day-to-day work a member does. admin: everything you hold. Never more than your role in the org grants. Omitted: the platform’s default (agent_access.default_token_scope). |
org_id | string | null | no | Limit the token to one of your organizations. Omitted: the token acts in the org named by the X-OpenTremor-Org header, else in the org you last used. |
expires_in_days | integer | null | no | Lifetime in days, at most agent_access.max_token_days. Omitted: that maximum. |
Response 201 (application/json)
{ "token_id": "string", "name": "string", "scope": "read", "org_id": "string", "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T00:00:00Z", "token": "string"}401— Unauthorized403— Not a signed-in session, or access tokens are turned off on this server
DELETE /v1/auth/me/access-tokens/{token_id}
Section titled “DELETE /v1/auth/me/access-tokens/{token_id}”Revoke an access token
Revokes one of the caller’s access tokens. Requires a signed-in session.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
token_id | string | yes |
204401— Unauthorized403— Forbidden404— Not one of the caller’s tokens
GET /v1/orgs/{org_id}/agent-access
Section titled “GET /v1/orgs/{org_id}/agent-access”Whether members’ access tokens act in this organization
Whether members’ access tokens act in this organization. API keys are not affected. Requires agent_access:manage (admin by default).
In the dashboard: Organization → Access → Service Accounts → Agent access.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "policy": "allowed"}| Field | Type | Required | Description |
|---|---|---|---|
policy | "allowed" | "read_only" | "forbidden" | yes | allowed: tokens act with their own scope. read_only: every token is capped at read here. forbidden: tokens get 403 here. |
401— Unauthorized403— Forbidden404— Not Found
PUT /v1/orgs/{org_id}/agent-access
Section titled “PUT /v1/orgs/{org_id}/agent-access”Set whether members’ access tokens act in this organization
Sets the organization’s policy for members’ access tokens:
allowed: tokens act with their own scope (the default).read_only: every token is capped at thereadscope in this org, and a token limited to this org can only be created withread.forbidden: tokens get403on every request in this org.
Applies to the next request each token makes. Audited as org.agent_access_update. Requires agent_access:manage (admin by default).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "policy": "allowed"}| Field | Type | Required | Description |
|---|---|---|---|
policy | "allowed" | "read_only" | "forbidden" | yes | allowed: tokens act with their own scope. read_only: every token is capped at read here. forbidden: tokens get 403 here. |
Response 200 (application/json)
{ "policy": "allowed"}| Field | Type | Required | Description |
|---|---|---|---|
policy | "allowed" | "read_only" | "forbidden" | yes | allowed: tokens act with their own scope. read_only: every token is capped at read here. forbidden: tokens get 403 here. |
401— Unauthorized403— Forbidden404— Not Found
Session
Section titled “Session”A person signs in with email and password and gets a short-lived JWT (session.access_ttl_minutes) in an httpOnly cookie; the dashboard uses this path. API keys and sessions are resolved the same way on every request. The /auth/me routes act on the signed-in account and need a human session.
POST /v1/auth/register
Section titled “POST /v1/auth/register”Register a new user
Public. Creates a user account, then logs the user in (sets the session cookie). Three mutually exclusive modes, based on which optional fields are set:
invite_tokenset → joins the org the invite grants access to, at the invite’s role. SeeGET /invite/{token}andPOST /invite/{token}/accept.org_nameset (and noinvite_token) → creates a new organization owned by the new user (roleowner). Returns403when a platform admin has turned offregistration.allow_public_org_creation.- Neither set → creates the account with no organization at all (
org_id/rolenull in the response and every later session). Every org-scoped endpoint returns403until the account creates an org (POST /orgs) or accepts an invite.
With org_name, the new org gets the mounted product’s starter content, the same as POST /orgs.
When the operator requires terms (registration.terms_version and terms_url, reported by GET /auth/registration-options), every mode also needs accepted_terms_version equal to the current version and returns 400 otherwise. The version and its date are recorded on the account.
Request body (application/json)
{ "password": "string", "name": "string", "org_name": "string", "invite_token": "string", "accepted_terms_version": "string"}| Field | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
password | string | yes | |
name | string | null | no | |
org_name | string | null | no | |
invite_token | string | null | no | |
accepted_terms_version | string | null | no | The version of the operator’s terms the user accepted. Required, and must equal the current one, when GET /auth/registration-options returns terms (400 otherwise); ignored when it returns none. |
Response 201 (application/json) — Registered; the session cookie is set
{ "user_id": "u1...", "org_id": "8f2a...", "role": "owner"}400—accepted_terms_versionmissing or not the current version403—org_namegiven but public organization creation is turned off404—invite_tokenunknown, expired or revoked409— Email already registered
GET /v1/auth/registration-options
Section titled “GET /v1/auth/registration-options”What self-service registration currently allows — public, no auth
Public, no authentication. Reports what self-service registration allows, so a sign-up page and the org-less onboarding page can hide the “create an organization” path instead of offering it and failing with 403 on submit.
allow_public_org_creation mirrors registration.allow_public_org_creation (GET /admin/settings); false means POST /auth/register with org_name and POST /orgs for a non-superadmin return 403. terms carries the version and links of the operator’s terms that sign-up must accept (registration.terms_*), or null when the operator requires none. It reads the live settings, so a PATCH /admin/settings change applies on the next call.
Advisory only: it carries no tenant data, and POST /auth/register and POST /orgs remain the enforcement points. A client that ignores it still gets the 403.
Response 200 (application/json)
{ "allow_public_org_creation": true, "terms": { "version": "string", "terms_url": "string", "privacy_url": "string" }}POST /v1/auth/session
Section titled “POST /v1/auth/session”Log in
Public. Verifies email and password and sets the session cookie. A user who belongs to several organizations lands in the one they last scoped to: their last login, switch, invitation acceptance or departure. If that membership is gone or deactivated, the first active membership is used. Call POST /auth/session/switch to move; the next login keeps that choice. A user with no organization at all (see POST /auth/register) logs in with org_id/role null, not an error.
If the account has two-factor authentication on, no session cookie is set here. The response carries mfa_token and methods instead (no user/org_id/role); complete login with POST /auth/session/2fa.
Request body (application/json)
{ "password": "string"}Response 200 (application/json) — Logged in (session cookie set), or a 2FA challenge (mfa_token, no cookie)
{ "user": { "user_id": "u1...", "created_at": "2026-01-01T00:00:00Z", "is_active": true, "two_factor_enabled": false }, "org_id": "8f2a...", "role": "owner", "is_superadmin": false}401— Wrong email or password, or the account is inactive
DELETE /v1/auth/session
Section titled “DELETE /v1/auth/session”Log out
Clears the session cookie in this browser. Other devices signed in to the same account keep their sessions. To end every session at once, change the password (POST /auth/me/password), which revokes all of them except the caller’s. An administrator can end every session of an account by deactivating it or resetting its password or 2FA.
Response 200 (application/json)
{ "detail": "Logged out"}POST /v1/auth/session/2fa
Section titled “POST /v1/auth/session/2fa”Complete login after a two-factor challenge
Public. Redeems the mfa_token from a POST /auth/session response that required a second factor. code is checked first as a current TOTP code, then as an unused recovery code; a matched recovery code is consumed and cannot be reused. On success the response and the session cookie are the same as POST /auth/session.
Request body (application/json)
{ "mfa_token": "string", "code": "string"}200— Logged in; the session cookie is set401—mfa_tokenexpired or invalid, orcodematches neither a current TOTP code nor an unused recovery code
GET /v1/auth/me
Section titled “GET /v1/auth/me”Get the current session’s identity
Resolves the caller’s API key or session cookie into a user/org/role triple, plus the permissions that role holds in the org. The dashboard calls it on page load. Any authenticated principal may call it.
useris null for an API key: no human account backs a machine key.access_token_idis set when the caller acts through one of the person’s access tokens;permissionsis then capped by the token’s scope.permissionslists every permissionroleholds in the org; check it before offering an action. It is empty for an org-less account.email_verification_requiredistrueonly whenregistration.require_verified_emailis on and the account is unverified. Every org-scoped call then returns403.organization_lockedreflectsPATCH /admin/organizations/{org_id}/lock.mfa_requiredistrueonly for a human session whose org requires 2FA, when the session came from no SSO connection and the account has not enrolled. Alwaysfalsefor an API key.sign_in_methodispassword,sso,googleormicrosoft, and null for an API key.sign_in_method_allowedisfalsewhen the org does not accept that method; every org-scoped call then returns403.
Response 200 (application/json)
{ "user": { "user_id": "u1...", "created_at": "2026-01-01T00:00:00Z", "is_active": true, "two_factor_enabled": false }, "org_id": "8f2a...", "role": "owner", "permissions": [ "api_keys:manage", "audit:read", "members:manage" ], "is_superadmin": false, "organization_locked": false, "mfa_required": false, "sign_in_method": "password", "sign_in_method_allowed": true, "allowed_sign_in_methods": [ "password", "sso", "social" ], "email_verified": true, "email_verification_required": false}401— No valid API key or session
PATCH /v1/auth/me
Section titled “PATCH /v1/auth/me”Update the current user’s own profile
Updates the caller’s own profile; only name today. Requires a human session: an API key has no user document to update. Returns the updated user, the same shape as GET /auth/me’s user.
In the dashboard: Account in the user menu, Profile tab.
Request body (application/json)
{ "name": "string"}Response 200 (application/json)
{ "user_id": "string", "email": "string", "name": "string", "created_at": "2026-01-01T00:00:00Z", "is_active": true, "two_factor_enabled": false, "has_password": true}| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | yes | |
email | string | yes | |
name | string | null | no | |
created_at | string (date-time) | yes | |
is_active | boolean | yes | |
two_factor_enabled | boolean | no | |
has_password | boolean | no | Whether the account has a local password, and so can use the password and two-factor endpoints under /auth/me. False for an account created through an SSO connection or a social login provider. |
400— API-key principal401— No session
DELETE /v1/auth/me
Section titled “DELETE /v1/auth/me”Delete the current user’s own account
Deletes the caller’s own account. Requires a human session. The caller proves it is them with password, or, for an account that signs in only through an identity provider, by typing its email address in confirm_email.
Removes the account with its linked identities and 2FA secret, every membership and team membership, the caller’s access tokens and connected apps, and the caller from email notification channels. Audit events keep the user id as their actor for retention.audit_days.
For each organization the caller alone owns, hand_over names the active member who becomes its owner, or lock locks it. A locked organization keeps its data until a platform admin unlocks or deletes it. GET /auth/me/succession lists these organizations and their candidates.
In the dashboard: Account in the user menu, Your data tab, Delete account.
Request body (application/json)
{ "hand_over": { "key": "string" }, "lock": [ "string" ], "password": "string", "confirm_email": "string"}| Field | Type | Required | Description |
|---|---|---|---|
hand_over | object | no | org_id → user_id of the active member who becomes that organization’s owner. |
lock | string[] | no | org_ids to lock instead. A locked organization keeps its data; a platform administrator can unlock or delete it. |
password | string | null | no | |
confirm_email | string | null | no |
200— Account deleted; the session cookie is cleared400— API-key principal, orconfirm_emaildoes not match401— Wrong or missing password409— An organization the caller alone owns has no decision; the body lists them
GET /v1/auth/me/succession
Section titled “GET /v1/auth/me/succession”The organizations the caller alone owns, and who could take each over
What a client asks before DELETE /auth/me or leaving an organization: each organization the caller alone owns, with its other active members. Each one goes in hand_over, or the organization in lock.
Response 200 (application/json)
{ "organizations": [ { "org_id": "3b17...", "name": "Acme", "candidates": [ { "user_id": "7c2e...", "name": "Ada" } ] } ]}400— API-key principal401— No session
GET /v1/auth/me/export
Section titled “GET /v1/auth/me/export”Download everything the platform holds about the current user
Everything the platform holds about the caller, as one JSON document: the account, its organizations and teams, its access tokens and connected apps, and the audit events where the caller is the actor. Secrets are left out. An organization’s own data is GET /orgs/{org_id}/export.
In the dashboard: Account, Your data tab, Download my data.
200400— API-key principal401— No session
POST /v1/auth/me/password
Section titled “POST /v1/auth/me/password”Change the current user’s own password
Changes the caller’s own password. Requires the current password; an admin reset does not. Not available to SSO-backed accounts (auth_provider != 'local'), which have no local password.
Signs the account out everywhere else: every other browser and device holding a session is rejected from its next request on. The caller stays signed in on a new session cookie returned with this response.
In the dashboard: Account in the user menu, Sign-in tab.
Request body (application/json)
{ "current_password": "string", "new_password": "string"}200— Password changed400— API-key principal, or the account authenticates through SSO401— No session, orcurrent_passwordis wrong
POST /v1/auth/me/2fa/enroll
Section titled “POST /v1/auth/me/2fa/enroll”Begin TOTP enrollment
Starts TOTP enrollment. Returns a QR-scannable provisioning URI and the same secret for manual entry. 2FA is not on yet: call POST /auth/me/2fa/confirm with a code from the authenticator app to finish. Calling this again before confirming replaces the pending secret. Requires a human session on a local account.
In the dashboard: Account in the user menu, Sign-in tab.
Response 200 (application/json)
{ "secret_provisioning_uri": "string", "manual_entry_code": "string"}400— API-key principal, or the account authenticates through SSO401— No session
POST /v1/auth/me/2fa/confirm
Section titled “POST /v1/auth/me/2fa/confirm”Confirm TOTP enrollment
Checks code against the pending secret from POST /auth/me/2fa/enroll. On success it turns 2FA on and returns 10 one-time recovery codes, shown once and never again. Each one replaces a TOTP code at POST /auth/session/2fa if the authenticator device is lost.
Request body (application/json)
{ "code": "string"}Response 200 (application/json) — 2FA on; the recovery codes are shown once
{ "recovery_codes": [ "string" ]}400— No pending enrollment, API-key principal, or the account authenticates through SSO401—codedoes not match the pending secret
POST /v1/auth/me/2fa/disable
Section titled “POST /v1/auth/me/2fa/disable”Turn off two-factor authentication
Turns two-factor authentication off. Requires the current password, like POST /auth/me/password: turning a security control off needs the same proof of account control as changing one.
Request body (application/json)
{ "current_password": "string"}Response 200 (application/json) — 2FA off
{ "detail": "string"}400— API-key principal, or the account authenticates through SSO401—current_passwordis wrong
GET /v1/auth/me/organizations
Section titled “GET /v1/auth/me/organizations”List organizations the current user belongs to
Every organization the caller belongs to, for the dashboard’s org switcher. Requires a human session: an API key is scoped to one organization and has no memberships to list.
Response 200 (application/json)
[ { "org_id": "string", "name": "string", "role": "string" }]401— No session, or an API-key principal
GET /v1/auth/me/invitations
Section titled “GET /v1/auth/me/invitations”Invitations waiting for the current user
Every still-valid invitation addressed to this account’s email (POST /orgs/{org_id}/invites with an email). Redeemed, revoked and expired ones are left out, so every row can be accepted. Requires a human session.
It lets a person find an invitation to a second organization without an invite URL reaching them: this deployment sends no email.
Open invitations (created without an email) are never listed: they are bearer links with no intended recipient. Rows carry invite_id, never the token: the caller has already proved who they are by signing in.
Response 200 (application/json) — The pending invitations, possibly none
[ { "invite_id": "string", "org_name": "string", "role": "string", "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T00:00:00Z" }]401— No session, or an API-key principal
POST /v1/auth/me/invitations/{invite_id}/accept
Section titled “POST /v1/auth/me/invitations/{invite_id}/accept”Accept an invitation addressed to the current user
The counterpart to POST /invite/{token}/accept for an invitation the caller found on their own list rather than through a link: same membership, no bearer token. Accepts only an invitation addressed to this account’s email.
Also re-scopes the session to the org just joined, like POST /auth/session/switch. Without that, an org-less account would join an org and keep a session that belongs to no org.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
invite_id | string | yes |
Response 200 (application/json) — Joined; the session is re-scoped to the new org
{ "org_id": "8f2a...", "role": "member"}401— No session, or an API-key principal404— Not on this account’s invitation list: unknown, expired, revoked or addressed to someone else, on purpose indistinguishable
POST /v1/auth/session/switch
Section titled “POST /v1/auth/session/switch”Switch the session to a different organization
Re-scopes the session cookie to org_id, when the caller has a membership there. The response has the same shape as POST /auth/session. Requires a human session: an API key belongs to one org and cannot switch.
Request body (application/json)
{ "org_id": "string"}200— Switched; the session cookie is re-issued for the new org401— No session, or an API-key principal403— The caller is not a member oforg_id
OAuth for agents
Section titled “OAuth for agents”OAuth 2.1 for hosted MCP clients that connect with the person’s consent (OpenTremor-platform#0032). Clients are public (no secret) and must use PKCE with S256. Access tokens last 3600 seconds; refresh tokens last 30 days and rotate on every use. Disconnecting an app revokes its tokens.
GET /.well-known/oauth-authorization-server
Section titled “GET /.well-known/oauth-authorization-server”OAuth authorization server metadata
Public. RFC 8414 metadata for hosted MCP clients that connect with the person’s consent.
Response 200 (application/json)
{}POST /oauth/register
Section titled “POST /oauth/register”Register an OAuth client
Public. RFC 7591 registration of a public client: no secret, PKCE required. Redirect URIs must be https, or http on localhost.
Request body (application/json)
{ "redirect_uris": [ "string" ], "client_name": "string", "token_endpoint_auth_method": "none"}201400— Bad Request429— Too Many Requests
GET /oauth/authorize
Section titled “GET /oauth/authorize”Start an authorization
Public. Checks the client, its redirect URI and the PKCE challenge (S256 only), then sends the browser to the dashboard’s consent page.
200302— Found400— Bad Request
POST /oauth/token
Section titled “POST /oauth/token”Exchange a code or a refresh token for an access token
Public. Form-encoded (RFC 6749). grant_type is authorization_code (with code, code_verifier, redirect_uri, client_id) or refresh_token (with refresh_token, client_id). Access tokens last 3600 seconds; refresh tokens last 30 days and rotate on every use. Errors follow RFC 6749 (invalid_grant, …).
200400— Bad Request429— Too Many Requests
GET /v1/oauth/authorize/request
Section titled “GET /v1/oauth/authorize/request”The authorization request the consent page shows
What the consent page shows. Requires a signed-in session.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
request | string | yes |
Response 200 (application/json)
{ "client_name": "string", "redirect_host": "string", "requested_scope": "read"}POST /v1/oauth/authorize/decision
Section titled “POST /v1/oauth/authorize/decision”Approve or deny an authorization
Approves or denies an authorization: {request, approve, scope, org_id}. Returns redirect_to, the client’s redirect URI with the code or the error. Requires a signed-in session. The session cookie is SameSite=Lax, so another site cannot submit this for the person (OpenTremor-platform#0032).
Request body (application/json)
{ "request": "string", "approve": true, "scope": "read", "org_id": "string"}| Field | Type | Required | Description |
|---|---|---|---|
request | string | yes | The signed request the consent page was opened with. |
approve | boolean | yes | |
scope | "read" | "write" | "admin" | no | |
org_id | string | null | no |
Response 200 (application/json)
{ "redirect_to": "string"}400— Bad Request403— Forbidden
GET /v1/auth/me/connected-apps
Section titled “GET /v1/auth/me/connected-apps”The apps you connected through OAuth
The apps the caller connected through OAuth. Requires a signed-in session.
Response 200 (application/json)
{ "apps": [ { "grant_id": "string", "client_name": "string", "scope": "read", "org_id": "string", "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T00:00:00Z" } ]}DELETE /v1/auth/me/connected-apps/{grant_id}
Section titled “DELETE /v1/auth/me/connected-apps/{grant_id}”Disconnect an app
Deletes the grant and every access token it issued. Requires a signed-in session.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
grant_id | string | yes |
204403— Forbidden404— Not Found