{ "openapi": "3.1.0", "info": { "title": "Infrastructure Auth API", "version": "1.0.0", "description": "Authentication as a service: passwordless sign-in by an 8-character email code (with an RFC 8628-style polling variant for headless agents), Google sign-in, sessions as RS256 JWTs verifiable via JWKS, an OAuth 2.1 authorization server for MCP clients (scopes `auth:read`, `auth:write`), and a management API for organizations, applications, end users, configuration and API keys.\n\n**Credentials.** Apps send `X-API-Key` (`pu_` in the browser, `ak_` on the server) plus `Authorization: Bearer `. An agent with no account can bootstrap itself: `POST /auth/code/start` (no key) → a human reads the code → `POST /auth/code/verify` → `POST /organizations` → `POST /application/{organizationId}` → `POST /api-keys`.\n\n**Contract.** Errors are `{ \"error\": { \"code\", \"message\", \"details\"? } }` with a stable `code`; collections are `{ items, page: { limit, offset, total, hasMore } }`. OAuth endpoints (`/oauth/*`, `/.well-known/*`) follow their RFCs instead.\n\nThe MCP server (`/mcp/{applicationId}`) is documented separately at https://myinfrastructure.click/products/auth/llms-mcp.txt.", "contact": { "name": "Infrastructure", "url": "https://myinfrastructure.click/contact" }, "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://auth.worker.myinfrastructure.click" } ], "externalDocs": { "description": "Full product documentation for developers and agents", "url": "https://myinfrastructure.click/products/auth/llms.txt" }, "tags": [ { "name": "Health", "description": "Liveness and public status." }, { "name": "Discovery", "description": "Well-known documents: JWKS and OAuth metadata." }, { "name": "OAuth", "description": "OAuth 2.1 authorization server (authorization code + PKCE) used by MCP clients." }, { "name": "Sign-in", "description": "The email code: the only way to prove identity." }, { "name": "Session", "description": "Read, refresh, list and revoke sessions." }, { "name": "Account", "description": "Profile, OAuth connections and application branding." }, { "name": "Social sign-in", "description": "Sign in with a provider using the application owner's own OAuth client." }, { "name": "Recent accounts", "description": "Per-browser sign-in shortcuts (HttpOnly cookie on this host)." }, { "name": "Organizations", "description": "The caller's organizations and plan." }, { "name": "Applications", "description": "Applications owned by an organization." }, { "name": "Application users", "description": "End users of an application." }, { "name": "Application organizations", "description": "Tenant organizations of an application's end users and their members." }, { "name": "Impersonation", "description": "Support tool: act as an end user for 15 minutes, with an audit trail." }, { "name": "Configurations", "description": "Per-application configuration." }, { "name": "API keys", "description": "Public (`pu_`) and secret (`ak_`) application keys." }, { "name": "Insights", "description": "Search and statistics." } ], "paths": { "/": { "get": { "operationId": "getHealth", "summary": "Health check", "description": "Liveness probe. Always answers 200 while the worker is up.", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Worker is up.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "service", "timestamp" ], "properties": { "status": { "const": "ok" }, "service": { "type": "string", "examples": [ "riligar-auth-worker" ] }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/status": { "get": { "operationId": "getStatus", "summary": "Service status", "description": "Public status report. Probes the database and the token-signing keys; each check is isolated, so a failing dependency becomes a `down` item instead of a 500. The overall `status` is the worst status among the checks (a check slower than 400 ms is `degraded`).", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Status report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusReport" } } } } } } }, "/.well-known/jwks.json": { "get": { "operationId": "getJwks", "summary": "JSON Web Key Set", "description": "Public keys (RS256) that verify every session and OAuth access token issued by Auth. Verify tokens locally with this set instead of calling `/auth/session` on every request.", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "The key set (RFC 7517). `keys` is empty only if the signing key is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Jwks" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "getOAuthAuthorizationServerMetadata", "summary": "OAuth authorization server metadata", "description": "RFC 8414 metadata for the OAuth 2.1 authorization server (authorization code + PKCE S256, public clients identified by a client ID metadata document URL).", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "Authorization server metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationServerMetadata" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "getOAuthProtectedResourceMetadata", "summary": "Protected resource metadata (MCP)", "description": "RFC 9728 metadata for the MCP endpoint `/mcp` served on this host: which authorization server issues its tokens and which scopes it understands.", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "Protected resource metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedResourceMetadata" } } } } } } }, "/.well-known/oauth-protected-resource/mcp/{id}": { "get": { "operationId": "getOAuthProtectedResourceMetadataForApplication", "summary": "Protected resource metadata for an application MCP", "description": "RFC 9728 metadata for the per-application MCP endpoint `/mcp/{id}`. The `resource` returned here becomes the `aud` of the access token.", "tags": [ "Discovery" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID (the suffix of the MCP URL).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Protected resource metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedResourceMetadata" } } } } } } }, "/oauth/authorize": { "get": { "operationId": "oauthAuthorize", "summary": "Start an OAuth authorization (consent screen)", "description": "Browser navigation endpoint. Validates the client (its `client_id` is an HTTPS URL of a client metadata document) and the `redirect_uri`, then either renders the consent page (HTML), redirects to the sign-in bridge when the browser has no session for the application that owns `resource`, or redirects back to `redirect_uri` with `error`, `error_description`, `iss` and `state`. Errors that happen before the client and redirect URI are validated are returned as JSON and never redirected. PKCE S256 and `resource` (RFC 8707) are mandatory.", "tags": [ "OAuth" ], "security": [ { "sessionCookie": [] }, {} ], "parameters": [ { "name": "client_id", "in": "query", "required": true, "description": "HTTPS URL of the client ID metadata document.", "schema": { "type": "string", "format": "uri" } }, { "name": "redirect_uri", "in": "query", "required": true, "description": "Must be listed in the client metadata document.", "schema": { "type": "string", "format": "uri" } }, { "name": "response_type", "in": "query", "required": true, "description": "Only `code` is supported.", "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "code_challenge", "in": "query", "required": true, "description": "PKCE code challenge.", "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": false, "description": "Only `S256` is accepted.", "schema": { "type": "string", "enum": [ "S256" ] } }, { "name": "resource", "in": "query", "required": true, "description": "Absolute https URI of the protected resource, without fragment. Must be registered by an application (`oauth.resources`).", "schema": { "type": "string", "format": "uri" } }, { "name": "scope", "in": "query", "required": false, "description": "Space-separated scopes. Granted scopes are narrowed to what the user may hold.", "schema": { "type": "string", "examples": [ "auth:read auth:write" ] } }, { "name": "state", "in": "query", "required": false, "description": "Opaque value echoed back to `redirect_uri`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Consent page.", "content": { "text/html": { "schema": { "type": "string" } } } }, "302": { "description": "Redirect to the sign-in bridge (`/oauth/login`) or back to `redirect_uri` with an OAuth error.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Invalid client or redirect URI (`invalid_client`, `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } } } } }, "/oauth/token": { "post": { "operationId": "oauthToken", "summary": "Exchange a code or refresh token for an access token", "description": "OAuth 2.1 token endpoint for public clients (no client authentication). `authorization_code` requires `code`, `code_verifier`, `client_id` and `redirect_uri` matching the authorization; `resource`, if resent, must equal the authorized one. `refresh_token` rotates the refresh token (the old one stops working) and re-evaluates the granted scopes. Access tokens are RS256 JWTs valid for 3600 s. Errors follow RFC 6749, not the platform error envelope.", "tags": [ "OAuth" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "Tokens issued. Sent with `Cache-Control: no-store`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "`invalid_request`, `invalid_grant`, `invalid_target` or `unsupported_grant_type`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } } } } }, "/auth/code/start": { "post": { "operationId": "startCode", "summary": "Send a sign-in code by email", "description": "The only way in: emails an 8-character code valid for 10 minutes, single use, 5 attempts. Creates the account on first use (there is no separate sign-up), and answers the same whether or not the email already had an account. A new start replaces the previous pending code for the same email. With a `pu_`/`ak_` key the account belongs to that application; without a key it is a platform account (the one that can create organizations, applications and keys). Rate limits: 5/min per IP and 3 per 10 min per recipient address.", "tags": [ "Sign-in" ], "security": [ { "publicKey": [] }, { "secretKey": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "maxLength": 120, "description": "Used as the display name if the account is created." } } } } } }, "responses": { "200": { "description": "Code sent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "sent", "deviceCode", "expiresIn", "interval" ], "properties": { "sent": { "const": true }, "deviceCode": { "type": "string", "description": "Opaque 64-hex handle for `/auth/code/poll`. Keep it secret." }, "expiresIn": { "type": "integer", "description": "Seconds until the code expires (600)." }, "interval": { "type": "integer", "description": "Minimum polling interval in seconds (5)." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/auth/code/verify": { "post": { "operationId": "verifyCode", "summary": "Trade the code for a session", "description": "Presents the emailed code (case and hyphen insensitive) together with the email and returns the session in one call. Marks the email as verified. Send the same API key used on `/auth/code/start`. Wrong code: 400 with `details.attemptsLeft`; expired: 410; fifth wrong attempt destroys the request and answers 429 (the `code` field of that 429 is currently `INTERNAL_ERROR`, because the handler emits a code outside the catalogue). Rate limit: 10/min per IP.", "tags": [ "Sign-in" ], "security": [ { "publicKey": [] }, { "secretKey": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string", "examples": [ "ABCD-EFGH" ] } } } } } }, "responses": { "200": { "description": "Signed in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResult" } } }, "headers": { "set-auth-token": { "description": "The session token (same value as `token` in the body). Exposed to browsers via CORS for clients on their own domains.", "schema": { "type": "string" } }, "set-cookie": { "description": "Session cookie `riligar.session_token[.]`, only issued when the request comes from a platform origin.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "410": { "description": "The code expired (`VALIDATION_ERROR` with status 410). Start again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many wrong attempts (request destroyed) or IP rate limit (`RATE_LIMITED`, with `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/code/approve": { "post": { "operationId": "approveCode", "summary": "Approve a pending code without issuing a session", "description": "The approving side of the headless flow: marks the request approved so that the agent polling `/auth/code/poll` receives the session. Returns no token. Same validation, attempt counter and rate limit as `/auth/code/verify`.", "tags": [ "Sign-in" ], "security": [ { "publicKey": [] }, { "secretKey": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Approved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "approved" ], "properties": { "approved": { "const": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "410": { "description": "The code expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many wrong attempts or IP rate limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/code/poll": { "post": { "operationId": "pollCode", "summary": "Poll for the session (headless agents)", "description": "RFC 8628-style polling for an agent that cannot read the inbox. Poll every `interval` seconds until someone presents the code via `/auth/code/approve`. While pending the answer is 428 (`code: UNPROCESSABLE`); polling too fast answers 429 (`code: RATE_LIMITED`) with a larger `details.interval`; an expired request answers 400 (`code: EXPIRED`); an unknown, consumed or raced device code answers 400 (`code: FORBIDDEN`). No API key is read: the device code identifies the request. Rate limit: 60/min per IP.", "tags": [ "Sign-in" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "deviceCode" ], "properties": { "deviceCode": { "type": "string", "minLength": 64, "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Approved: session issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResult" } } }, "headers": { "set-auth-token": { "description": "The session token (same value as `token` in the body). Exposed to browsers via CORS for clients on their own domains.", "schema": { "type": "string" } }, "set-cookie": { "description": "Session cookie `riligar.session_token[.]`, only issued when the request comes from a platform origin.", "schema": { "type": "string" } } } }, "400": { "description": "Expired, denied or missing `deviceCode`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Not approved yet. `details.interval` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Polling too fast (`details.interval`) or IP rate limit (`details.retryAfter`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/code/peek": { "post": { "operationId": "peekCode", "summary": "Read the pending code of a synthetic test address", "description": "For automated tests only. Returns the pending code of an address under the application's configured synthetic email domain (`authentication.syntheticEmailDomain`), so a test can walk the real sign-in. Requires the SECRET key (`ak_`). Every refusal (domain not configured, real address, no pending or expired code) is the same 404.", "tags": [ "Sign-in" ], "security": [ { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "The pending code.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/session": { "get": { "operationId": "getSession", "summary": "Get the current session", "description": "Resolves the caller's session (impersonation cookie, then `Authorization: Bearer`, then session cookie). With an API key the session must belong to that application. `token` is included when the client cannot already hold it (it came by cookie, the session is impersonated, or the header token did not resolve). `impersonation` is present only for an impersonated session. With a valid API key and no session, answers 200 with only `application`.", "tags": [ "Session" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] }, {} ], "responses": { "200": { "description": "The session, or only the application when no session resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/refresh": { "post": { "operationId": "refreshSession", "summary": "Rotate the session token", "description": "Issues a new token for the current session (same session id, new expiry); the old token stops working.", "tags": [ "Session" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "responses": { "200": { "description": "New token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResult" } } }, "headers": { "set-auth-token": { "description": "The session token (same value as `token` in the body). Exposed to browsers via CORS for clients on their own domains.", "schema": { "type": "string" } }, "set-cookie": { "description": "Session cookie `riligar.session_token[.]`, only issued when the request comes from a platform origin.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/sign-out": { "post": { "operationId": "signOut", "summary": "Sign out", "description": "Ends the user's sessions in this application and clears this application's session cookie. Always answers 200, even without a session.", "tags": [ "Session" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] }, {} ], "responses": { "200": { "description": "Signed out.", "content": { "application/json": { "schema": { "type": "object", "required": [ "signedOut" ], "properties": { "signedOut": { "const": true } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/list-sessions": { "get": { "operationId": "listSessions", "summary": "List the user's sessions", "description": "All sessions of the current user, newest first. Not paginated: `page.total` and `page.hasMore` are `null`.", "tags": [ "Session" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "responses": { "200": { "description": "Sessions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/revoke-session-by-id": { "post": { "operationId": "revokeSession", "summary": "Revoke one session", "description": "Deletes one of the current user's sessions. An id that is not the user's is silently ignored.", "tags": [ "Session" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/revoke-other-sessions": { "post": { "operationId": "revokeOtherSessions", "summary": "Revoke every other session", "description": "Deletes all sessions of the current user except the one making the call.", "tags": [ "Session" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/impersonation/{id}/end": { "post": { "operationId": "endImpersonation", "summary": "End an impersonation", "description": "Ends the impersonation and deletes its session. What authorizes is presenting that impersonation's own token (impersonation cookie or Bearer). Idempotent: an already ended impersonation is returned as is. Clears the impersonation cookie.", "tags": [ "Impersonation" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Impersonation record ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The ended impersonation record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonationRecord" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/update-user": { "post": { "operationId": "updateUser", "summary": "Update the profile", "description": "Updates `name` and/or `image` of the current user. The email cannot be changed. `image: \"\"` removes the photo.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "image": { "type": "string", "maxLength": 716800, "description": "PNG/JPEG/GIF/WebP base64 data URL or an https URL; empty string removes it. Max 500 KB image." } } } } } }, "responses": { "200": { "description": "Updated user.", "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/User" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/list-connections": { "get": { "operationId": "listConnections", "summary": "List authorized OAuth connections", "description": "OAuth grants (e.g. MCP connectors) the current user authorized and has not revoked. Not paginated.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "responses": { "200": { "description": "Connections.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/revoke-connection": { "post": { "operationId": "revokeConnection", "summary": "Revoke an OAuth connection", "description": "Revokes one of the current user's OAuth grants; its refresh token stops working.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connectionId" ], "properties": { "connectionId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/application/by-api-key": { "get": { "operationId": "getApplicationByApiKey", "summary": "Get the application of an API key", "description": "Public application info (name, logo...) for the key in `X-API-Key`. Used by the SDK to brand the sign-in screen. Callable from any origin.", "tags": [ "Account" ], "security": [ { "publicKey": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "The application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/providers": { "get": { "operationId": "listProviders", "summary": "List social sign-in providers", "description": "Providers the application configured and enabled. Never returns client IDs or secrets.", "tags": [ "Social sign-in" ], "security": [ { "publicKey": [] }, { "secretKey": [] }, {} ], "responses": { "200": { "description": "Providers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "provider", "name" ], "properties": { "provider": { "type": "string" }, "name": { "type": "string" } } } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/sign-in/{provider}": { "get": { "operationId": "startSocialSignIn", "summary": "Start social sign-in (redirect)", "description": "Full-page navigation. Validates `redirect` (or the request `Origin`) against the application's allowed origins, then redirects to the provider with PKCE. The public key may come in `X-API-Key` or, on this route only, in `?api_key=` (a secret `ak_` there is ignored). After the provider, `/auth/callback/{provider}` redirects to the destination with `#token=` on success or `?social_error=` on failure. Rate limit: 10/min per IP.", "tags": [ "Social sign-in" ], "security": [ { "publicKey": [] }, { "publicKeyQuery": [] }, {} ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider ID. This build supports `google`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "examples": [ "google" ] } }, { "name": "redirect", "in": "query", "required": false, "description": "Where to return after sign-in. Must match an allowed origin of the application. Defaults to the request Origin.", "schema": { "type": "string", "format": "uri" } } ], "responses": { "302": { "description": "Redirect to the provider authorization page.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/callback/{provider}": { "get": { "operationId": "socialCallback", "summary": "Social sign-in callback", "description": "The redirect URI to register at the provider (`https://auth.worker.myinfrastructure.click/auth/callback/{provider}`). Called by the browser coming back from the provider; the single-use `state` authenticates it. Redirects to the validated destination with `#token=` (success), or with `?social_error=` one of `denied`, `link_required`, `email_unusable`, `exchange_failed`, `provider_unavailable`, `state_invalid`. Rate limit: 30/min per IP.", "tags": [ "Social sign-in" ], "security": [], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider ID. This build supports `google`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "examples": [ "google" ] } }, { "name": "state", "in": "query", "required": true, "description": "State issued by `/auth/sign-in/{provider}` or `/auth/link/{provider}`.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "description": "Authorization code from the provider.", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Set by the provider when the person cancelled.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the destination with the token in the fragment or the failure in `social_error`.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/link/{provider}": { "post": { "operationId": "startSocialLink", "summary": "Start linking a provider to the account", "description": "From inside a session: returns the provider authorization URL that links the provider account to the current user. The callback returns to `redirect` without creating a new session.", "tags": [ "Social sign-in" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider ID. This build supports `google`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "examples": [ "google" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect": { "type": "string", "format": "uri", "description": "Defaults to the request Origin; must be an allowed origin." } } } } } }, "responses": { "200": { "description": "Authorization URL to navigate to.", "content": { "application/json": { "schema": { "type": "object", "required": [ "authorizeUrl" ], "properties": { "authorizeUrl": { "type": "string", "format": "uri" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/unlink/{provider}": { "post": { "operationId": "unlinkSocialProvider", "summary": "Unlink a provider from the account", "description": "Removes the link between the current user and the provider account.", "tags": [ "Social sign-in" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider ID. This build supports `google`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "examples": [ "google" ] } } ], "responses": { "200": { "description": "Unlinked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "unlinked" ], "properties": { "unlinked": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/linked-providers": { "get": { "operationId": "listLinkedProviders", "summary": "List linked providers", "description": "Provider accounts linked to the current user.", "tags": [ "Social sign-in" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "responses": { "200": { "description": "Linked providers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedProvider" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/recent-accounts": { "get": { "operationId": "listRecentAccounts", "summary": "List recent accounts of this browser", "description": "Browser-only sign-in shortcuts kept in an HttpOnly cookie on this host, one list per application. Requires an allowed `Origin`.", "tags": [ "Recent accounts" ], "security": [ { "publicKey": [] }, { "secretKey": [] }, {} ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "The calling page's origin. Must be in the application's allowed origins, otherwise 403.", "schema": { "type": "string", "format": "uri" } }, { "name": "__Host-riligar.recent_accounts", "in": "cookie", "required": false, "description": "HttpOnly cookie holding this browser's lists (set by this API).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "This browser's recent accounts for the application (at most 5).", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecentAccount" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "rememberRecentAccount", "summary": "Remember the current account", "description": "Puts the CURRENT session's email on top of this browser's list (never an email from the body). An impersonated session writes nothing.", "tags": [ "Recent accounts" ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "The calling page's origin. Must be in the application's allowed origins, otherwise 403.", "schema": { "type": "string", "format": "uri" } }, { "name": "__Host-riligar.recent_accounts", "in": "cookie", "required": false, "description": "HttpOnly cookie holding this browser's lists (set by this API).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$", "default": "code", "description": "How the person signed in (e.g. `code`, `google`)." } } } } } }, "responses": { "200": { "description": "This browser's recent accounts for the application (at most 5).", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecentAccount" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/recent-accounts/{email}": { "delete": { "operationId": "forgetRecentAccount", "summary": "Forget a recent account", "description": "Removes one email from this browser's list. No session needed.", "tags": [ "Recent accounts" ], "security": [ { "publicKey": [] }, { "secretKey": [] }, {} ], "parameters": [ { "name": "email", "in": "path", "required": true, "description": "URL-encoded email to remove.", "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "description": "The calling page's origin. Must be in the application's allowed origins, otherwise 403.", "schema": { "type": "string", "format": "uri" } }, { "name": "__Host-riligar.recent_accounts", "in": "cookie", "required": false, "description": "HttpOnly cookie holding this browser's lists (set by this API).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string", "description": "The removed email." }, "deleted": { "const": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/plan": { "get": { "operationId": "getPlan", "summary": "Get the plan notice", "description": "The caller's Auth plan as it applies to creating applications. Never fails: `state: unknown` when billing cannot be reached. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Organizations" ], "responses": { "200": { "description": "Plan notice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanNotice" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/organizations": { "get": { "operationId": "listOrganizations", "summary": "List the caller's organizations", "description": "Organizations the caller is a member of, with the caller's role. Not paginated. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Organizations" ], "responses": { "200": { "description": "Organizations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMembership" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] }, "post": { "operationId": "saveOrganization", "summary": "Create or update an organization", "description": "Without `id`: creates an organization with the caller as `owner` (201). With `id`: updates it; requires owner/admin (200). Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string", "description": "Present to update." }, "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/organizations/{id}": { "delete": { "operationId": "deleteOrganization", "summary": "Delete an organization", "description": "Soft-deletes an organization. Owner only. Refused with 409 `HAS_RESOURCES` (`details.applicationsCount`) while it still has applications. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/applications/{id}": { "get": { "operationId": "listApplications", "summary": "List applications of an organization", "description": "Applications of the organization, newest first, with counts and effective configuration. Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Applications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Default 50, clamped to 200; `page.limit` reports the value actually applied.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of items to skip. Default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated applications.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationSummary" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/{id}": { "get": { "operationId": "getApplication", "summary": "Get an application", "description": "One application. Requires membership in its organization. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Applications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] }, "post": { "operationId": "saveApplication", "summary": "Create or update an application", "description": "NOTE: here `{id}` is the ORGANIZATION ID. Without `body.id`: creates an application in that organization (201), subject to the plan limit (402 `PLAN_LIMIT` or `SUBSCRIPTION_REQUIRED`, with diagnostic `details`). With `body.id`: updates that application (200). Requires owner/admin of the organization. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Applications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID that owns (or will own) the application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Application ID, present to update." }, "name": { "type": "string", "description": "Required to create." }, "description": { "type": "string" }, "image": { "type": "string" }, "environment": { "type": "string", "default": "development" }, "organizationId": { "type": "string", "description": "Optional; if sent it must equal the path organization ID." } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] }, "delete": { "operationId": "deleteApplication", "summary": "Delete an application", "description": "Soft-deletes an application. Owner only. Refused with 409 `HAS_RESOURCES` (`details.usersCount`, `details.activeKeysCount`) while it has users or active keys. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Applications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/{id}/move": { "post": { "operationId": "moveApplication", "summary": "Move an application to another organization", "description": "Requires owner/admin in both the current and the target organization. 422 `UNPROCESSABLE` if it already belongs to the target. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Applications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetOrganizationId" ], "properties": { "targetOrganizationId": { "type": "string" } } } } } }, "responses": { "200": { "description": "The moved application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/users/{id}": { "get": { "operationId": "listApplicationUsers", "summary": "List users of an application", "description": "End users of the application, newest first. Not paginated. Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserSummary" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] }, "post": { "operationId": "saveApplicationUser", "summary": "Create or update an application user", "description": "Pre-registers an end user (unverified until their first code sign-in) with a default organization (201), or updates the user given by `id` (200). If the email already exists, returns it with `alreadyExisted: true` (200). Sets no credential. Requires owner/admin. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "name" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated or already existing.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "properties": { "alreadyExisted": { "type": "boolean" } } } ] } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/users/{id}/{userId}": { "delete": { "operationId": "deleteApplicationUser", "summary": "Delete an application user", "description": "Deletes the user (and, by cascade, their sessions and memberships). Requires owner/admin. Answers 200 even if the user did not exist. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "User ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/users/{id}/{userId}/impersonate": { "post": { "operationId": "startImpersonation", "summary": "Impersonate an application user", "description": "Support tool for humans, not an agent surface. Opens a 15-minute session as the target user, recorded in the audit trail, and sets the impersonation cookie. Requires owner/admin; impersonating yourself is 400. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Impersonation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "Target user ID.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "201": { "description": "Impersonation started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonationStarted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/impersonations/{id}": { "get": { "operationId": "listImpersonations", "summary": "List the impersonation audit trail", "description": "Impersonations of the application, newest first, searchable. Any member of the owning organization can read it. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Impersonation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Default 50, clamped to 200; `page.limit` reports the value actually applied.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of items to skip. Default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "required": false, "description": "Search in actor/target name and email and in the reason.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated trail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ImpersonationTrailItem" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/impersonations/{id}/end-all": { "post": { "operationId": "endAllImpersonations", "summary": "End every open impersonation of an application", "description": "Closes all open impersonations of the application and deletes their sessions. Requires owner/admin. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Impersonation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "How many were ended.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ended" ], "properties": { "ended": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/organizations/{id}": { "get": { "operationId": "listApplicationOrganizations", "summary": "List an application's customer organizations", "description": "Organizations that belong to the application's end users (tenants), with member counts. Not paginated. Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organizations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationWithCount" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] }, "post": { "operationId": "saveApplicationOrganization", "summary": "Create or update a customer organization", "description": "Without `body.id`: creates a tenant organization in the application (201). With `body.id`: updates it (200). `membersCount` in the response is always 0. Requires owner/admin. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationWithCount" } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationWithCount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] }, "delete": { "operationId": "deleteApplicationOrganization", "summary": "Delete a customer organization", "description": "NOTE: here `{id}` is the ORGANIZATION ID. Soft-deletes a tenant organization. Requires owner/admin of the organization that owns the application. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/organizations/{id}/{organizationId}": { "get": { "operationId": "getApplicationOrganization", "summary": "Get a customer organization", "description": "One tenant organization of the application, with its member count. Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "description": "Organization ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationWithCount" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/organizations/{id}/{organizationId}/members": { "get": { "operationId": "listApplicationOrganizationMembers", "summary": "List members of a customer organization", "description": "Members, newest first. Not paginated. Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "description": "Organization ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Members.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] }, "post": { "operationId": "saveApplicationOrganizationMember", "summary": "Add a member or change their role", "description": "Adds a user of the same application to the organization (201) or updates their role/active flag (200). Requires owner/admin. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "description": "Organization ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "default": "member" }, "isActive": { "type": "boolean", "description": "Only applied when updating an existing member." } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "201": { "description": "Added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/application/organizations/{id}/{organizationId}/members/{userId}": { "delete": { "operationId": "removeApplicationOrganizationMember", "summary": "Remove a member", "description": "Removes the membership. Removing the last owner is refused with 422 `UNPROCESSABLE`. Requires owner/admin. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Application organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "description": "Organization ID.", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "User ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/configurations/{id}": { "get": { "operationId": "getConfiguration", "summary": "Get application configuration", "description": "Effective configuration (defaults merged with saved values). Social provider secrets are masked: `clientSecret` is `null` and `hasClientSecret` tells whether one is stored. Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Configurations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configuration" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/configurations": { "post": { "operationId": "saveConfiguration", "summary": "Save application configuration", "description": "Deep-merges the given sections into the stored configuration (arrays are replaced). For `authentication.socialProviders.`, a `clientSecret` of `null` keeps the stored secret. Requires owner/admin. 503 when the secret vault is not configured. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Configurations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Configuration" }, { "type": "object", "required": [ "applicationId" ], "properties": { "applicationId": { "type": "string" } } } ], "description": "Application ID plus any subset of configuration sections." } } } }, "responses": { "200": { "description": "Saved configuration row.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "applicationId", "data" ], "properties": { "id": { "type": "string" }, "applicationId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Configuration" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys of an application", "description": "Key metadata only (prefix, type, status); the full key is never returned again. Not paginated. Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "API keys" ], "parameters": [ { "name": "applicationId", "in": "query", "required": true, "description": "Application ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Keys.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "description": "Creates a `public` (`pu_`) or `secret` (`ak_`) key. The full key is returned in `key` ONLY in this response. Requires owner/admin. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "API keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "applicationId", "type" ], "properties": { "applicationId": { "type": "string" }, "type": { "type": "string", "enum": [ "public", "secret" ] } } } } } }, "responses": { "201": { "description": "Created key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/api-keys/{id}": { "delete": { "operationId": "deleteApiKey", "summary": "Delete an API key", "description": "Deletes the key. Requires owner/admin. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "API keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/search": { "get": { "operationId": "search", "summary": "Search users and organizations of an application", "description": "Up to 5 users and 5 organizations matching `q` (min 2 characters; shorter returns an empty list). Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Insights" ], "parameters": [ { "name": "applicationId", "in": "query", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search term (min 2 characters).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Hits.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } }, "/statistics": { "get": { "operationId": "getStatistics", "summary": "Get application statistics", "description": "New users, sign-ins and active users in the period vs the previous period of equal length. Default period: the last 7 days. Requires membership. Requires a session token (any application) whose user is a member of at least one organization; otherwise 401/403. From a browser, CORS on this path is only granted to platform origins; server-to-server calls are unaffected.", "tags": [ "Insights" ], "parameters": [ { "name": "applicationId", "in": "query", "required": true, "description": "Application ID.", "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": false, "description": "Period start (any Date-parsable value, e.g. ISO 8601).", "schema": { "type": "string" } }, { "name": "end", "in": "query", "required": false, "description": "Period end. Defaults to now.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Statistics" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "publicKey": [] }, { "bearerAuth": [], "secretKey": [] }, { "sessionCookie": [] }, { "sessionCookie": [], "publicKey": [] } ] } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "WRONG_AUDIENCE", "INSUFFICIENT_SCOPE", "NOT_FOUND", "CONFLICT", "NAME_TAKEN", "EXPIRED", "HAS_RESOURCES", "VALIDATION_ERROR", "UNPROCESSABLE", "RATE_LIMITED", "PAYLOAD_TOO_LARGE", "PLAN_LIMIT", "SUBSCRIPTION_REQUIRED", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "UPSTREAM_ERROR" ], "description": "Stable machine code from the closed catalogue. Act on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable (Portuguese); may change." }, "details": { "type": "object", "additionalProperties": true, "description": "What the client can act on (e.g. `retryAfter`, `attemptsLeft`, `interval`, plan limits)." }, "retriable": { "type": "boolean", "description": "Present (true) for RATE_LIMITED, SERVICE_UNAVAILABLE and UPSTREAM_ERROR." } } } } }, "OAuthError": { "type": "object", "required": [ "error" ], "description": "RFC 6749 error body (used only by the OAuth endpoints).", "properties": { "error": { "type": "string", "examples": [ "invalid_request", "invalid_client", "invalid_grant", "invalid_target", "unsupported_grant_type", "access_denied" ] }, "error_description": { "type": "string" } } }, "Page": { "type": "object", "required": [ "limit", "offset", "total", "hasMore" ], "properties": { "limit": { "type": "integer", "description": "Applied page size (for unpaginated lists, the number of items)." }, "offset": { "type": "integer" }, "total": { "type": [ "integer", "null" ], "description": "`null` when the list is not paginated and was not counted." }, "hasMore": { "type": [ "boolean", "null" ], "description": "`null` when `total` is `null`." } } }, "User": { "type": "object", "required": [ "id", "email", "name", "emailVerified" ], "properties": { "id": { "type": "string" }, "applicationId": { "type": [ "string", "null" ], "description": "`null` for a platform account." }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "emailVerified": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "UserSummary": { "type": "object", "required": [ "id", "email", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "image": { "type": [ "string", "null" ] }, "emailVerified": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Session": { "type": "object", "required": [ "id", "expiresAt" ], "properties": { "id": { "type": "string" }, "token": { "type": "string", "description": "Present on sign-in and refresh." }, "expiresAt": { "type": "string", "format": "date-time" } } }, "SignInResult": { "type": "object", "required": [ "user", "token", "session" ], "properties": { "user": { "$ref": "#/components/schemas/User" }, "token": { "type": "string", "description": "Session JWT (RS256), valid 7 days. Send as `Authorization: Bearer`." }, "session": { "$ref": "#/components/schemas/Session" } } }, "SessionInfo": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "session": { "$ref": "#/components/schemas/Session" }, "token": { "type": "string", "description": "Only when the client cannot already hold it." }, "impersonation": { "type": "object", "description": "Only for an impersonated session.", "properties": { "id": { "type": [ "string", "null" ] }, "actor": { "type": [ "string", "null" ], "description": "The operator's email." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "application": { "oneOf": [ { "$ref": "#/components/schemas/Application" }, { "type": "null" } ] } } }, "SessionSummary": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] } } }, "RevokedResult": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "const": true } } }, "Connection": { "type": "object", "required": [ "id", "clientId", "resource", "scope" ], "properties": { "id": { "type": "string" }, "clientId": { "type": "string", "format": "uri" }, "resource": { "type": "string", "format": "uri" }, "scope": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "isMcp": { "type": "boolean" }, "neverExpires": { "type": "boolean" } } }, "LinkedProvider": { "type": "object", "required": [ "id", "provider", "name" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "lastLoginAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "RecentAccount": { "type": "object", "required": [ "email", "method", "lastUsedAt" ], "properties": { "email": { "type": "string", "format": "email" }, "method": { "type": "string" }, "lastUsedAt": { "type": "integer", "description": "Unix epoch milliseconds." } } }, "Application": { "type": "object", "required": [ "id", "organizationId", "name" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "environment": { "type": "string", "examples": [ "development", "production" ] }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ApplicationSummary": { "allOf": [ { "$ref": "#/components/schemas/Application" }, { "type": "object", "properties": { "apiKeysCount": { "type": "integer" }, "usersCount": { "type": "integer" }, "organizationsCount": { "type": "integer" }, "configurationData": { "type": [ "string", "null" ], "description": "Raw stored configuration JSON." }, "configurations": { "$ref": "#/components/schemas/Configuration" } } } ] }, "Organization": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "applicationId": { "type": [ "string", "null" ], "description": "`null` for platform organizations; the application ID for an application's tenant organizations." }, "name": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OrganizationMembership": { "allOf": [ { "$ref": "#/components/schemas/Organization" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "isActive": { "type": [ "boolean", "null" ] }, "memberSince": { "type": "string", "format": "date-time" } } } ] }, "OrganizationWithCount": { "allOf": [ { "$ref": "#/components/schemas/Organization" }, { "type": "object", "properties": { "membersCount": { "type": "integer" } } } ] }, "Member": { "type": "object", "required": [ "id", "userId", "role" ], "properties": { "id": { "type": "string", "description": "Membership ID." }, "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "image": { "type": [ "string", "null" ] }, "emailVerified": { "type": "boolean" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "isActive": { "type": [ "boolean", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "ApiKey": { "type": "object", "required": [ "id", "type", "prefix" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "public", "secret" ] }, "prefix": { "type": "string", "description": "First 15 characters of the key." }, "isActive": { "type": [ "boolean", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApiKeyCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "required": [ "key", "applicationId" ], "properties": { "applicationId": { "type": "string" }, "key": { "type": "string", "description": "The full key (`pu_…` or `ak_…`). Shown only once." }, "secretHash": { "type": "string", "description": "Stored HMAC of the key (currently included in this response)." } } } ] }, "Configuration": { "type": "object", "description": "Application configuration. Sections are deep-merged with the defaults.", "additionalProperties": true, "properties": { "authentication": { "type": "object", "additionalProperties": true, "properties": { "emailEnabled": { "type": "boolean" }, "phoneEnabled": { "type": "boolean" }, "usernameEnabled": { "type": "boolean" }, "ssoConnections": { "type": "array", "items": {} }, "multiFactorEnabled": { "type": "boolean" }, "domainRestrictions": { "type": "array", "items": {} }, "syntheticEmailDomain": { "type": "string", "description": "Email domain whose codes `/auth/code/peek` may reveal. Empty disables peek." }, "socialProviders": { "type": "object", "description": "Keyed by provider ID (e.g. `google`).", "additionalProperties": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean" }, "clientId": { "type": "string" }, "clientSecret": { "type": [ "string", "null" ], "description": "Write-only. Read back as `null`; send `null` to keep the stored secret." }, "hasClientSecret": { "type": "boolean", "readOnly": true } } } } } }, "session": { "type": "object", "additionalProperties": true, "properties": { "sessionLifetime": { "type": "integer" }, "inactivityTimeout": { "type": "integer" }, "multiSessionEnabled": { "type": "boolean" } } }, "organization": { "type": "object", "additionalProperties": true, "properties": { "organizationName": { "type": "string" }, "enabled": { "type": "boolean" } } }, "applications": { "type": "object", "additionalProperties": true, "properties": { "applicationName": { "type": "string" }, "apiKeysEnabled": { "type": "boolean" }, "planType": { "type": "string" } } }, "oauth": { "type": "object", "properties": { "resources": { "type": "array", "description": "Resource servers (RFC 8707) this application authorizes, matched by prefix.", "items": { "type": "object", "properties": { "resource": { "type": "string", "format": "uri" }, "identity": { "type": "string", "enum": [ "product", "platform" ] } } } } } }, "customization": { "type": "object", "additionalProperties": true, "properties": { "accountPortal": { "type": "object", "additionalProperties": true, "properties": { "primaryColor": { "type": "string" }, "logoUrl": { "type": "string" }, "origins": { "type": "array", "items": { "type": "string" }, "description": "Allowed origins of the application." } } }, "avatarProvider": { "type": "string" }, "emailTemplates": { "type": "array", "items": {} }, "smsTemplates": { "type": "array", "items": {} } } } } }, "PlanNotice": { "type": "object", "required": [ "state", "plan", "limit", "message" ], "properties": { "state": { "type": "string", "enum": [ "active", "free", "none", "unknown" ] }, "plan": { "type": [ "string", "null" ] }, "limit": { "type": [ "integer", "null" ], "description": "`null` when unlimited or unknown." }, "message": { "type": [ "string", "null" ], "description": "Banner text, only when the owner has more applications than the plan covers." } } }, "ImpersonationParty": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" } } }, "ImpersonationRecord": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "actorUserId": { "type": "string" }, "targetUserId": { "type": "string" }, "applicationId": { "type": "string" }, "sessionId": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ImpersonationStarted": { "type": "object", "required": [ "id", "token", "session" ], "properties": { "id": { "type": "string" }, "actor": { "$ref": "#/components/schemas/ImpersonationParty" }, "target": { "$ref": "#/components/schemas/ImpersonationParty" }, "applicationId": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "null" }, "expiresAt": { "type": "string", "format": "date-time" }, "token": { "type": "string", "description": "Impersonated session JWT (claims `imp`, `act`, `act_email`), valid 15 minutes." }, "session": { "$ref": "#/components/schemas/Session" } } }, "ImpersonationTrailItem": { "type": "object", "required": [ "id", "isActive" ], "properties": { "id": { "type": "string" }, "applicationId": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "isActive": { "type": "boolean" }, "actor": { "$ref": "#/components/schemas/ImpersonationParty" }, "target": { "$ref": "#/components/schemas/ImpersonationParty" } } }, "SearchHit": { "type": "object", "required": [ "type", "id", "title" ], "properties": { "type": { "type": "string", "enum": [ "user", "organization" ] }, "id": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "emailVerified": { "type": "boolean", "description": "Users only." } } }, "Statistics": { "type": "object", "properties": { "users": { "allOf": [ { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" }, "variation": { "type": "number", "description": "Percent change vs the previous period." } } }, { "type": "object", "properties": { "total": { "type": "integer" } } } ] }, "logins": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" }, "variation": { "type": "number", "description": "Percent change vs the previous period." } } }, "activeUsers": { "allOf": [ { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" }, "variation": { "type": "number", "description": "Percent change vs the previous period." } } }, { "type": "object", "properties": { "value": { "type": "integer", "description": "Users with a live session now." } } } ] }, "period": { "type": "object", "properties": { "current": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "previous": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } } } } } }, "StatusReport": { "type": "object", "required": [ "service", "status", "checkedAt", "checks" ], "properties": { "service": { "const": "auth" }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ] }, "checkedAt": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "required": [ "name", "status", "latencyMs" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ] }, "latencyMs": { "type": "integer" }, "metrics": { "type": "object", "additionalProperties": { "type": "number" } }, "error": { "const": "unavailable" } } } } } }, "Jwks": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "kty": { "type": "string" }, "kid": { "type": "string" }, "alg": { "type": "string" }, "use": { "type": "string" }, "n": { "type": "string" }, "e": { "type": "string" } } } } } }, "AuthorizationServerMetadata": { "type": "object", "required": [ "issuer", "authorization_endpoint", "token_endpoint", "jwks_uri" ], "properties": { "issuer": { "type": "string", "format": "uri" }, "authorization_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "jwks_uri": { "type": "string", "format": "uri" }, "scopes_supported": { "type": "array", "items": { "type": "string" }, "examples": [ [ "auth:read", "auth:write" ] ] }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "authorization_response_iss_parameter_supported": { "type": "boolean" }, "resource_indicators_supported": { "type": "boolean" }, "client_id_metadata_document_supported": { "type": "boolean" }, "service_documentation": { "type": "string", "format": "uri" } } }, "ProtectedResourceMetadata": { "type": "object", "required": [ "resource", "authorization_servers" ], "properties": { "resource": { "type": "string", "format": "uri" }, "authorization_servers": { "type": "array", "items": { "type": "string", "format": "uri" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } }, "resource_documentation": { "type": "string", "format": "uri", "description": "Only on the root document." } } }, "TokenRequest": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "code": { "type": "string", "description": "authorization_code: required." }, "code_verifier": { "type": "string", "description": "authorization_code: required (PKCE)." }, "client_id": { "type": "string", "format": "uri", "description": "authorization_code: must match the authorization. refresh_token: optional, checked if sent." }, "redirect_uri": { "type": "string", "format": "uri", "description": "authorization_code: must match the authorization." }, "resource": { "type": "string", "format": "uri", "description": "authorization_code: optional; must equal the authorized resource." }, "refresh_token": { "type": "string", "description": "refresh_token: required." } } }, "TokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "refresh_token", "scope" ], "properties": { "access_token": { "type": "string", "description": "RS256 JWT whose `aud` is the authorized resource." }, "token_type": { "const": "Bearer" }, "expires_in": { "type": "integer", "examples": [ 3600 ] }, "refresh_token": { "type": "string" }, "scope": { "type": "string", "examples": [ "auth:read auth:write" ] } } } }, "responses": { "BadRequest": { "description": "Invalid request (`VALIDATION_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, invalid or expired credential (`UNAUTHORIZED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated but not allowed (`FORBIDDEN`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found, or not visible to the caller (`NOT_FOUND`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The resource still has dependents (`HAS_RESOURCES`); `details` carries the counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "Plan limit reached (`PLAN_LIMIT`) or no active plan (`SUBSCRIPTION_REQUIRED`); `details` carries `current`, `limit`, `plan`, `resource`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "Valid request that is impossible in the current state (`UNPROCESSABLE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests (`RATE_LIMITED`, `details.retryAfter`).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Unexpected failure (`INTERNAL_ERROR`). Never carries internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServiceUnavailable": { "description": "A dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`). Retry later.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Session token returned by `/auth/code/verify`, `/auth/code/poll`, `/auth/refresh` or the social sign-in callback (`#token=`). RS256 JWT, verifiable with `/.well-known/jwks.json`; valid 7 days. OAuth access tokens issued by `/oauth/token` are NOT accepted by these REST routes (they are for MCP resource servers)." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "riligar.session_token", "description": "Session cookie set by Auth for platform origins (`*.myinfrastructure.click`, claude.ai, localhost) and product-line panels on their own zone. When an API key is sent, the cookie read is `riligar.session_token.`. Stripped from requests whose `Origin` is any other site, so third-party apps must use `bearerAuth`." }, "publicKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Application public key (`pu_…`). Safe to ship in a browser bundle. Identifies the application: sign-ins create/find users of that application and sessions must belong to it. An unknown or inactive key is treated as no key." }, "secretKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Application secret key (`ak_…`). Server-side only. Same role as the public key, and additionally required by `/auth/code/peek`." }, "publicKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Public key (`pu_…`) in the query string, accepted ONLY by `GET /auth/sign-in/{provider}` (a page navigation cannot send headers). A secret key here is ignored." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 (authorization code + PKCE S256) served by this API: /oauth/authorize and /oauth/token. The tokens it issues are for the MCP servers of the seven products, each validated by audience (RFC 8707); this API's own REST routes use a session or an API key.", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.worker.myinfrastructure.click/oauth/authorize", "tokenUrl": "https://auth.worker.myinfrastructure.click/oauth/token", "refreshUrl": "https://auth.worker.myinfrastructure.click/oauth/token", "scopes": { "auth:read": "Read your resources through an MCP server.", "auth:write": "Create, change and delete your resources through an MCP server." } } } } } } }