{ "openapi": "3.1.0", "info": { "title": "Lucion Identity API", "version": "6.6.6", "description": "Production API contract for Lucion Identity. Authentication supports passkeys and password accounts; passkeys remain available as a phishing-resistant sign-in method but are not required for account creation or password sign-in. Password proofs use a server-only pepper, per-credential salt, Cloudflare-safe chained PBKDF2 work factor, generic failures, rate limits, and lockout. Browser session mutations require the exact Lucion origin and CSRF proof. Server-to-server resources use OAuth 2.0 Bearer access tokens or one-time displayed, hash-only API keys. Scoped CLI application registration and webhook test mutations require narrow API-key scopes, explicit Idempotency-Key values, and never return one-time client secrets. Matching lifecycle events are durably queued before bounded outbound webhook delivery and routed only to the owning user or organization application audience. Successful sign-out and session revocation emit identity.session.revoked with only session_id, user_id, and a fixed non-secret reason. Maintained TypeScript, Python, and Go SDKs cover the tenant organization mutation and inspection surfaces plus scoped developer metadata reads with caller-supplied idempotency keys where mutations are supported. Developer reads require identity.developer.read and return only owner-filtered metadata with bounded opaque cursors. Versioned API surfaces advertise their lifecycle and reject unsupported requested versions before authentication or data access.", "contact": { "name": "Lucion Identity Developer Support", "url": "https://identity.lucionglobal.com/docs" }, "x-logo": { "url": "/assets/identity-brand/lucion-identity-horizontal.png", "altText": "Lucion Identity" } }, "servers": [ { "url": "https://identity.lucionglobal.com", "description": "Canonical production origin" } ], "externalDocs": { "description": "Human-readable API and webhook reference", "url": "https://identity.lucionglobal.com/docs" }, "x-lucion-api-version": "v1", "x-lucion-api-lifecycle": "current", "x-lucion-status-evidence": { "capabilities": "/api/v1/capabilities", "readiness": "/api/v1/readiness", "rehearsal": "/api/v1/rehearsal", "status_page": "/status", "fallback": "unavailable" }, "x-lucion-scim-concurrency": { "etag": "strong-opaque-resource-version", "meta_version": true, "if_none_match": 304, "if_match": 412, "wildcard_if_match": "supported" }, "x-lucion-versioning-policy": { "current": "v1", "supported": [ "v1" ], "deprecation_notice_days": 180, "request_header": "X-Lucion-API-Version", "response_header": "X-Lucion-API-Version", "lifecycle_header": "X-Lucion-API-Lifecycle", "sunset_header": "Sunset", "documentation": "/docs/versioning", "scim_current": "scim-2.0" }, "tags": [ { "name": "Runtime" }, { "name": "Enrollment" }, { "name": "Sessions" }, { "name": "Recovery" }, { "name": "Authorization" }, { "name": "Privacy" }, { "name": "Developer" }, { "name": "Webhooks" }, { "name": "OAuth/OIDC" }, { "name": "SCIM" } ], "paths": { "/api/health": { "get": { "tags": [ "Runtime" ], "summary": "Read safe release and runtime status", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/docs/ask": { "post": { "tags": [ "Documentation" ], "summary": "Ask the bounded documentation assistant", "description": "Requires the exact site Origin. Accepts a bounded documentation question and page context, rate-limits by a keyed client identifier, and returns advisory text only. Provider API keys and response bodies remain server-side; Lucion AI is preferred when configured and Gemini 3 Flash is the fallback.", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "429": { "$ref": "#/components/responses/Json429" }, "502": { "$ref": "#/components/responses/Json502" }, "503": { "$ref": "#/components/responses/Json503" }, "504": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/status": { "get": { "tags": [ "Runtime" ], "summary": "Read authentication capability status", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/passkeys/capabilities": { "get": { "tags": [ "Runtime" ], "summary": "Read passkey and WebAuthn capability contract", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/password/capabilities": { "get": { "tags": [ "Runtime" ], "summary": "Read password authentication capability contract", "description": "Returns safe password authentication metadata. Password accounts require verified email enrollment; password proofs are independently gated, rate-limited, and lockout-protected.", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/email-otp/capabilities": { "get": { "tags": [ "Runtime" ], "summary": "Read independent email OTP sign-in capability", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/verification/capabilities": { "get": { "tags": [ "Runtime" ], "summary": "Read six-digit verification UX contract", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/interaction/capabilities": { "get": { "tags": [ "Runtime" ], "summary": "Read Trust UX capability contract", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/enrollment/capabilities": { "get": { "tags": [ "Enrollment" ], "summary": "Read email and passkey enrollment readiness", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/email/capabilities": { "get": { "tags": [ "Runtime" ], "summary": "Read transactional email and Resend webhook status", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/session/capabilities": { "get": { "tags": [ "Sessions" ], "summary": "Read session security capability status", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/recovery/capabilities": { "get": { "tags": [ "Recovery" ], "summary": "Read recovery capability status", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/authorization/capabilities": { "get": { "tags": [ "Authorization" ], "summary": "Read organization and Lyra authorization status", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/federation/capabilities": { "get": { "tags": [ "Enterprise Federation" ], "summary": "Read the enterprise federation capability contract", "description": "Returns safe provider-level status. Inbound OIDC may be enabled only behind the independent federation gate; SAML protocol execution remains independently gated until conformance review. SAML metadata validation is required before a connection can be activated. No provider credentials, tenant identifiers, or assertion data are returned.", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/auth/federation/discovery": { "get": { "tags": [ "Enterprise Federation" ], "summary": "Discover an enabled federation connection for a verified email domain", "description": "Requires the exact production Origin. The response never includes an organization identifier or provider credentials; protocol execution remains independently gated.", "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email", "maxLength": 320 } } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/federation/oidc/start": { "get": { "tags": [ "Enterprise Federation" ], "summary": "Start an inbound OIDC authorization-code transaction", "description": "Requires the independently enabled federation gate and exact production Origin. The server fetches bounded HTTPS provider metadata, creates an expiring state/nonce/PKCE transaction, and redirects without exposing provider credentials.", "parameters": [ { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "responses": { "302": { "description": "Redirect to the validated provider authorization endpoint" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/federation/oidc/callback": { "get": { "tags": [ "Enterprise Federation" ], "summary": "Complete an inbound OIDC transaction", "description": "Canonical-origin callback. The code is exchanged with PKCE, then the signed ID token is validated for RS256, issuer, audience, nonce, time, and verified email before tenant-bound JIT membership and a federated session are created. Transactions are single-use and failures redirect with only a safe classification.", "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the sign-in surface with a safe result classification" } } } }, "/api/v1/capabilities": { "get": { "tags": [ "Runtime" ], "summary": "Read the authoritative public capability matrix", "description": "Returns safe live, gated, degraded, manual, and planned capability classifications derived from the runtime readiness and rehearsal boundaries. This endpoint never grants access and never returns secrets, provider bodies, tenant identifiers, session material, or verification data.", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/organizations/{id}/federation/connections/{connection_id}/health": { "get": { "tags": [ "Enterprise Federation" ], "summary": "Run a read-only provider metadata preflight", "description": "Requires tenant-bound session access; a supplied Origin must match the request origin. Re-fetches bounded HTTPS OIDC or SAML IdP metadata and returns only a safe validation status/classification; provider bodies, credentials, claims, tenant identifiers, and session material are never returned. A valid preflight does not enable SAML protocol execution or change connection state.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "422": { "$ref": "#/components/responses/Json422" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/v1/readiness": { "get": { "tags": [ "Runtime" ], "summary": "Read the production readiness matrix", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/v1/rehearsal": { "get": { "tags": [ "Runtime" ], "summary": "Read the fail-closed launch rehearsal state", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/api/v1/me": { "get": { "tags": [ "Runtime" ], "summary": "Read the authenticated identity profile", "security": [ { "BearerAuth": [ "identity.profile.read" ] }, { "BearerAuth": [ "identity.email.read" ] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } }, "patch": { "tags": [ "Runtime" ], "summary": "Update the authenticated identity profile", "description": "Requires identity.profile.write and Idempotency-Key. Updates display_name, locale, and timezone only; email ownership changes require a separate verification flow. Successful changes emit privacy-minimized identity.user.updated events through the durable outbox.", "security": [ { "BearerAuth": [ "identity.profile.write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/v1/me/memberships": { "get": { "tags": [ "Organization Management" ], "summary": "Read the authenticated Lucion ID's own organization memberships", "description": "Returns active organization memberships for the bearer credential owner only. The endpoint accepts no organization selector, so it cannot be used to enumerate another user's or tenant's memberships.", "security": [ { "BearerAuth": [ "identity.organization.read" ] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/v1/organizations": { "get": { "tags": [ "Organization Management" ], "summary": "List the bearer token's organization", "description": "Server-to-server read. Requires an organization-bound bearer credential with identity.organization.read. The response is limited to that credential's tenant; unbound credentials are rejected.", "security": [ { "BearerAuth": [ "identity.organization.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/v1/organizations/{id}": { "get": { "tags": [ "Organization Management" ], "summary": "Read an organization", "description": "Server-to-server read. The requested organization must exactly match the bearer credential's organization binding. Administrative mutations remain on the session, CSRF, and step-up protected browser contract.", "security": [ { "BearerAuth": [ "identity.organization.read" ] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" } } } }, "/api/v1/organizations/{id}/members": { "get": { "tags": [ "Organization Management" ], "summary": "List organization members", "description": "Stable descending created_at/id cursor pagination, with a bounded limit from 1 through 100. Pass next_cursor unchanged.", "security": [ { "BearerAuth": [ "identity.organization.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/v1/organizations/{id}/invitations": { "get": { "tags": [ "Organization Management" ], "summary": "List organization invitations", "description": "Stable descending created_at/id cursor pagination, with a bounded limit from 1 through 100. Pass next_cursor unchanged.", "security": [ { "BearerAuth": [ "identity.organization.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/v1/organizations/{id}/groups": { "get": { "tags": [ "Organization Management" ], "summary": "List organization groups", "description": "Stable descending created_at/id cursor pagination, with a bounded limit from 1 through 100. Pass next_cursor unchanged.", "security": [ { "BearerAuth": [ "identity.organization.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/v1/organizations/{id}/groups/{group_id}/members": { "get": { "tags": [ "Organization Management" ], "summary": "List members of an organization group", "description": "Stable descending membership created_at/id cursor pagination, with a bounded limit from 1 through 100. Pass next_cursor unchanged.", "security": [ { "BearerAuth": [ "identity.organization.members.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" } } } }, "/api/v1/organizations/{id}/domains": { "get": { "tags": [ "Organization Management" ], "summary": "List verified organization domains", "description": "Stable descending created_at/id cursor pagination, with a bounded limit from 1 through 100. Pass next_cursor unchanged.", "security": [ { "BearerAuth": [ "identity.organization.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/v1/organizations/{id}/lyra/actions": { "get": { "tags": [ "Authorization" ], "summary": "List the organization Lyra action catalog", "description": "Stable descending created_at/id cursor pagination, with a bounded limit from 1 through 100. Pass next_cursor unchanged. Action execution remains separately gated and disabled by default.", "security": [ { "BearerAuth": [ "identity.organization.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/v1/privacy/export": { "get": { "tags": [ "Privacy" ], "summary": "Export the authenticated identity data boundary", "description": "Requires the dedicated identity.privacy.export scope. Returns the authenticated user's profile, memberships, consents, delegations, session metadata, authenticator metadata, and privacy-minimized activity. Hashes, tokens, cookies, verification codes, private keys, webhook secrets, provider bodies, and IP/user-agent material are never returned. The response is never cached.", "security": [ { "BearerAuth": [ "identity.privacy.export" ] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/privacy/deletion-request": { "get": { "tags": [ "Privacy" ], "summary": "Read the current account deletion-request state", "description": "Returns only the authenticated account's latest deletion-request metadata. No deletion is started by this read.", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "503": { "$ref": "#/components/responses/Json503" } } }, "post": { "tags": [ "Privacy" ], "summary": "Request account deletion for manual privacy review", "description": "Requires exact Origin, CSRF, recent passkey step-up, explicit confirmation DELETE_MY_ACCOUNT, and Idempotency-Key. Creates a pending user-bound request only; it never immediately deletes an identity, session, passkey, organization membership, or credential.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "202": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/privacy/deletion-request/cancel": { "post": { "tags": [ "Privacy" ], "summary": "Cancel a pending account deletion request", "description": "Requires exact Origin, CSRF, recent passkey step-up, explicit confirmation CANCEL_DELETION, and Idempotency-Key. Only a pending request may be cancelled; no identity data is deleted by cancellation.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/openapi.json": { "get": { "tags": [ "Runtime" ], "summary": "Fetch this machine-readable API contract", "responses": { "200": { "description": "OpenAPI 3.1 JSON document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/auth/enrollment/start": { "post": { "tags": [ "Enrollment" ], "summary": "Start verified-email enrollment", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "202": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "429": { "$ref": "#/components/responses/Json429" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/enrollment/verify-email": { "post": { "tags": [ "Enrollment" ], "summary": "Verify the six-digit email code", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" } } } }, "/api/auth/enrollment/password/complete": { "post": { "tags": [ "Enrollment" ], "summary": "Create an account with a verified email and password", "description": "Requires a verified email enrollment token and a valid password. Creates the account and stores only the server-side password proof; it never issues a session.", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "409": { "$ref": "#/components/responses/Json409" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/enrollment/resend-email": { "post": { "tags": [ "Enrollment" ], "summary": "Request a replacement verification email", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "429": { "$ref": "#/components/responses/Json429" } } } }, "/api/auth/enrollment/passkey/options": { "post": { "tags": [ "Enrollment" ], "summary": "Issue one-time WebAuthn registration options", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/auth/enrollment/passkey/complete": { "post": { "tags": [ "Enrollment" ], "summary": "Verify and persist a passkey", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/auth/signin/passkey/options": { "post": { "tags": [ "Sessions" ], "summary": "Issue a one-time passkey sign-in challenge", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "429": { "$ref": "#/components/responses/Json429" } } } }, "/api/auth/signin/passkey/complete": { "post": { "tags": [ "Sessions" ], "summary": "Verify a passkey assertion and issue a secure session cookie", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/auth/signin/password": { "post": { "tags": [ "Sessions" ], "summary": "Verify a password and issue a secure session cookie", "description": "Requires the exact production Origin. Password proofs use a server-only pepper and per-credential salt, generic failure responses, bounded rate limits, and lockout after repeated failures. A passkey is not required.", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "429": { "$ref": "#/components/responses/Json429" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/signin/email-otp/start": { "post": { "tags": [ "Sessions" ], "summary": "Request a short-lived email sign-in code", "description": "Requires exact Origin and rate limits. Existing and unknown email addresses receive the same response. Codes are peppered HMAC-only, expire after 10 minutes, and are independently gated by AUTH_EMAIL_OTP_MODE.", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "202": { "$ref": "#/components/responses/Json200" }, "429": { "$ref": "#/components/responses/Json429" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/signin/email-otp/complete": { "post": { "tags": [ "Sessions" ], "summary": "Verify a single-use email code and issue a secure session", "description": "Requires exact Origin and rate limits. A code is bound to its challenge, expires after 10 minutes, permits at most five attempts, and is consumed once before session issuance.", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "429": { "$ref": "#/components/responses/Json429" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/password/set": { "post": { "tags": [ "Sessions" ], "summary": "Set or rotate a password credential", "description": "Requires an authenticated session, exact Origin, CSRF, and recent passkey step-up. Existing password sessions are revoked after replacement; no password or password hash is returned.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/session": { "get": { "tags": [ "Sessions" ], "summary": "Resolve the current session", "responses": { "200": { "$ref": "#/components/responses/Json200" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/oauth/connections": { "get": { "tags": [ "OAuth/OIDC" ], "summary": "List the current user's active OAuth and assistant connections", "description": "Returns names, granted scopes, connection type, and expiry only. Raw OAuth tokens are never exposed.", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/oauth/connections/{connection_id}": { "delete": { "tags": [ "OAuth/OIDC" ], "summary": "Revoke one of the current user's OAuth or assistant connections", "description": "Requires exact Origin, CSRF, and an authenticated session. Revokes the refresh-token family and every linked access token. The operation is safe to repeat.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^orf_[0-9a-fA-F-]{36}$" } } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" } } } }, "/api/auth/sessions": { "get": { "tags": [ "Sessions" ], "summary": "List active sessions for the current account", "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/api/auth/sessions/revoke": { "post": { "tags": [ "Sessions" ], "summary": "Revoke one owned session", "description": "Requires exact Origin, CSRF, and an authenticated session. A successful revocation emits identity.session.revoked through the durable webhook outbox without session credentials.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/auth/signout": { "post": { "tags": [ "Sessions" ], "summary": "Revoke the current session", "description": "Requires exact Origin and CSRF when authenticated. A successful sign-out emits identity.session.revoked through the durable webhook outbox without session credentials.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/auth/step-up/passkey/options": { "post": { "tags": [ "Sessions" ], "summary": "Issue a step-up passkey challenge", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/api/auth/step-up/passkey/complete": { "post": { "tags": [ "Sessions" ], "summary": "Complete passkey step-up", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/auth/step-up/password": { "post": { "tags": [ "Sessions" ], "summary": "Complete password re-authentication step-up", "description": "Requires an authenticated session, exact Origin, CSRF, a valid server-side password credential, bounded rate limits, and lockout protection. Sets a short-lived step-up timestamp; never issues a session or returns password or hash material.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "429": { "$ref": "#/components/responses/Json429" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/recovery/start": { "post": { "tags": [ "Recovery" ], "summary": "Start enumeration-resistant recovery proof", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "202": { "$ref": "#/components/responses/Json200" }, "429": { "$ref": "#/components/responses/Json429" } } } }, "/api/auth/recovery/resend": { "post": { "tags": [ "Recovery" ], "summary": "Resend a recovery code", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "429": { "$ref": "#/components/responses/Json429" } } } }, "/api/auth/recovery/verify": { "post": { "tags": [ "Recovery" ], "summary": "Verify recovery email proof without issuing a session", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" } } } }, "/api/auth/recovery/passkey/options": { "post": { "tags": [ "Recovery" ], "summary": "Issue replacement-passkey options after recovery proof", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/auth/recovery/passkey/complete": { "post": { "tags": [ "Recovery" ], "summary": "Complete replacement-passkey recovery", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" } } } }, "/api/auth/organizations": { "get": { "tags": [ "Authorization" ], "summary": "List organizations for the current session", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/api/auth/memberships": { "get": { "tags": [ "Organization Management" ], "summary": "Read the current Lucion ID's own D1 organization memberships", "description": "Returns the authenticated user's active memberships, roles, and groups. The query is derived from the session user and does not accept a tenant selector or expose other users' memberships.", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/authorization/evaluate": { "post": { "tags": [ "Authorization" ], "summary": "Evaluate an organization permission", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/auth/lyra/evaluate": { "post": { "tags": [ "Authorization" ], "summary": "Evaluate a scope-bound Lyra delegation", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/auth/lyra/respond": { "post": { "tags": [ "Authorization" ], "summary": "Request a bounded Groq-backed Lyra advisory response", "description": "Requires exact-origin CSRF-protected session access, active membership, an active delegation for the exact organization, application, agent, and lyra.chat scope, bounded input, and the server-only GROQ_API_KEY. This endpoint returns advisory text only and never executes tools, creates sessions, changes access, or returns the provider response body.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "429": { "$ref": "#/components/responses/Json429" }, "502": { "$ref": "#/components/responses/Json502" }, "503": { "$ref": "#/components/responses/Json503" }, "504": { "$ref": "#/components/responses/Json503" } } } }, "/api/auth/lyra/actions/execute": { "post": { "tags": [ "Authorization" ], "summary": "Submit a confirmed, delegated Lyra action boundary request", "description": "Requires exact Origin, CSRF, explicit confirmation, a matching delegation, and Idempotency-Key. The current guarded boundary records acceptance but does not execute an external action.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "202": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/organizations": { "get": { "tags": [ "Organization Management" ], "summary": "List organizations for the current session", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Create an organization with an Owner membership", "description": "Requires exact Origin, CSRF, recent passkey step-up, and Idempotency-Key for retry safety. No session is issued by organization creation.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Organization Management" ], "summary": "Read an organization and its policy/application summary", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } }, "patch": { "tags": [ "Organization Management" ], "summary": "Update organization settings", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/members": { "get": { "tags": [ "Organization Management" ], "summary": "List tenant-bound members and roles", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/organizations/{id}/members/{member_id}": { "patch": { "tags": [ "Organization Management" ], "summary": "Update a member role or status", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } }, "delete": { "tags": [ "Organization Management" ], "summary": "Revoke a membership without deleting the user", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/invitations": { "get": { "tags": [ "Organization Management" ], "summary": "List tenant-bound invitations", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Create and deliver an organization invitation", "description": "Requires admin step-up. Only the token hash and safe delivery classification are persisted; the invitation token is never returned.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "202": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/organizations/{id}/invitations/{invitation_id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invitation_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Organization Management" ], "summary": "Resend an organization invitation", "description": "Rotates the invitation proof hash before delivery. The invitation token is never returned.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "$ref": "#/components/responses/Json200" }, "202": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } }, "delete": { "tags": [ "Organization Management" ], "summary": "Revoke an organization invitation", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" } } } }, "/api/organizations/invitations/accept": { "post": { "tags": [ "Organization Management" ], "summary": "Accept an invitation for the authenticated email", "description": "Requires an existing authenticated session and exact email match. Acceptance adds a membership and never creates a session.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/organizations/{id}/delegated-admins": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "get": { "tags": [ "Organization Management" ], "summary": "List scoped delegated administrator grants", "description": "Lists tenant-bound delegated grants without secrets or session material. An active administrator or a grant with the exact delegations.read scope may read the records.", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Create a scoped delegated administrator grant", "description": "Owner-only, exact-origin, CSRF- and recent-passkey-step-up-protected mutation for an existing active member. Scopes use the organization delegation allowlist; expiry is limited to five minutes through 30 days; Owner targets and self-grants are rejected. Idempotency-Key is required. A grant never creates a session or changes the target to Owner.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/delegated-admins/{delegation_id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } }, { "name": "delegation_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "delete": { "tags": [ "Organization Management" ], "summary": "Revoke a delegated administrator grant", "description": "Revokes only an active grant in the requested organization. Requires exact-origin CSRF, recent passkey step-up, administrator authorization, and Idempotency-Key. Audit evidence and idempotency completion are committed with the revocation; replay returns no secret or session material.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/policies": { "get": { "tags": [ "Organization Management" ], "summary": "List organization policies", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Create or update an organization policy", "description": "Supports the optional requireSessionBinding boolean. When enabled, sensitive organization reads, permission evaluation, and organization administrator mutations require the request context to match hash-only IP and user-agent context captured at session issuance. This is session-context binding, not device attestation.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } }, "patch": { "tags": [ "Organization Management" ], "summary": "Update an organization policy", "description": "Supports the optional requireSessionBinding boolean. A changed or unavailable session context fails closed for sensitive organization reads, permission evaluation, and organization administrator mutations.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/organizations/{id}/policies/{policy_key}": { "delete": { "tags": [ "Organization Management" ], "summary": "Remove an organization policy and return to the default boundary", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "policy_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" } } } }, "/api/organizations/{id}/groups": { "get": { "tags": [ "Organization Management" ], "summary": "List organization groups", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Create an organization group", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/groups/{group_id}": { "patch": { "tags": [ "Organization Management" ], "summary": "Rename an organization group", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } }, "delete": { "tags": [ "Organization Management" ], "summary": "Delete an empty organization group", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/groups/{group_id}/members": { "get": { "tags": [ "Organization Management" ], "summary": "List group members", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Add an organization member to a group", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/groups/{group_id}/members/{membership_id}": { "delete": { "tags": [ "Organization Management" ], "summary": "Remove a member from a group", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" } } } }, "/api/organizations/{id}/roles": { "get": { "tags": [ "Organization Management" ], "summary": "List organization roles and permissions", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Create a custom organization role", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/organizations/{id}/roles/{role_id}": { "patch": { "tags": [ "Organization Management" ], "summary": "Update a custom organization role", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } }, "delete": { "tags": [ "Organization Management" ], "summary": "Delete an unused custom organization role", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/applications": { "get": { "tags": [ "Organization Management" ], "summary": "List organization application assignments", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Assign an application to an organization", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/organizations/{id}/applications/{application_id}": { "delete": { "tags": [ "Organization Management" ], "summary": "Disable an organization application assignment", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" } } } }, "/api/organizations/{id}/domains": { "get": { "tags": [ "Organization Management" ], "summary": "List organization domains", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Register a DNS-verifiable domain", "description": "Returns a one-time DNS TXT proof value; only its hash is persisted. Idempotency-Key prevents duplicate domain records without replaying the one-time proof.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/domains/{domain_id}": { "delete": { "tags": [ "Organization Management" ], "summary": "Delete an organization domain", "description": "Deletes a tenant-bound domain record with replay-safe mutation. A verified domain cannot be deleted while an active federation connection exists; disable federation first. The operation never deletes users or memberships.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/domains/{domain_id}/verify": { "post": { "tags": [ "Organization Management" ], "summary": "Verify a DNS TXT domain proof", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "422": { "$ref": "#/components/responses/Json422" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/organizations/{id}/federation/connections": { "get": { "tags": [ "Enterprise Federation" ], "summary": "List organization federation metadata", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } }, "post": { "tags": [ "Enterprise Federation" ], "summary": "Register federation metadata", "description": "Metadata is stored disabled and does not enable SAML assertions, OIDC callbacks, domain routing, or just-in-time provisioning. Activation later performs bounded provider metadata validation.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/organizations/{id}/federation/connections/{connection_id}": { "patch": { "tags": [ "Enterprise Federation" ], "summary": "Activate or disable a federation connection", "description": "Status changes require exact-origin session mutation protection, CSRF, recent passkey step-up, administrator authorization, and Idempotency-Key. Activating a connection first validates its bounded OIDC JSON or SAML 2.0 IdP metadata; provider failures return a safe classification and do not change state. Active metadata still requires the independent federation protocol gate before sign-in or discovery is available.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" }, "422": { "$ref": "#/components/responses/Json422" }, "503": { "$ref": "#/components/responses/Json503" } } }, "delete": { "tags": [ "Enterprise Federation" ], "summary": "Delete a disabled federation connection", "description": "Deletion is tenant-bound, replay-safe, and requires the connection to be disabled first. It never deletes users or memberships and never bypasses the independent federation protocol gate.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/organizations/{id}/lyra/actions": { "get": { "tags": [ "Authorization" ], "summary": "List schema-validated Lyra action catalog entries", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } }, "post": { "tags": [ "Authorization" ], "summary": "Register a schema-validated Lyra action", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/organizations/{id}/audit-events": { "get": { "tags": [ "Organization Management" ], "summary": "List tenant-bound organization audit events with cursor pagination", "description": "Returns stable descending occurred_at/id pages after tenant authorization. Metadata, secrets, tokens, provider bodies, and unrelated organization activity are never returned. Pass the opaque next_cursor unchanged.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/organizations/{id}/approvals": { "get": { "tags": [ "Organization Management" ], "summary": "List organization approval requests with cursor pagination", "description": "Returns stable descending created_at/id pages after tenant authorization. Pass the opaque next_cursor unchanged.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" } } }, "post": { "tags": [ "Organization Management" ], "summary": "Create an organization approval request with administrator step-up", "description": "Creates a pending record only. Requires exact-origin CSRF protection, recent passkey step-up, Owner/Admin authorization, and separation of duties at decision time. Idempotency-Key is optional but recommended for lost-response retries.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/organizations/{id}/approvals/{approval_id}": { "post": { "tags": [ "Organization Management" ], "summary": "Approve or reject a request with independent administrator step-up", "description": "Requires exact-origin CSRF protection, recent passkey step-up, Owner/Admin authorization, a pending request, and a different user from the requester. Approval records do not execute the requested action. Idempotency-Key is optional but recommended for lost-response retries.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/developer/applications": { "get": { "tags": [ "Developer" ], "summary": "List owned applications with cursor pagination", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" } } }, "post": { "tags": [ "Developer" ], "summary": "Register an application", "description": "Requires an authenticated Lucion session, exact Origin, CSRF proof, recent step-up, Idempotency-Key, and the per-user application-creation rate limit. Confidential client secrets are generated server-side, shown once, and stored only as one-way verifiers.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" }, "429": { "$ref": "#/components/responses/Json429" } } } }, "/api/v1/developer/applications": { "get": { "tags": [ "Developer" ], "summary": "List owned applications with a scoped bearer credential", "description": "Returns owner-scoped application metadata with bounded opaque cursors. Client secrets and application secret material are never returned.", "security": [ { "BearerAuth": [ "identity.developer.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/DeveloperApplications200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } }, "post": { "tags": [ "Developer" ], "summary": "Register an application with a scoped API key", "description": "Server-to-server mutation for CLI and automation. Requires an API key with identity.applications.manage, an Idempotency-Key, and never returns a client secret to the CLI surface. Browser application registration remains protected by session, exact Origin, CSRF, and passkey step-up.", "security": [ { "BearerAuth": [ "identity.applications.manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/developer/api-keys": { "get": { "tags": [ "Developer" ], "summary": "List owned API-key metadata with cursor pagination", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" } } }, "post": { "tags": [ "Developer" ], "summary": "Create a one-time displayed API key", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/v1/developer/api-keys": { "get": { "tags": [ "Developer" ], "summary": "List owned API-key metadata with a scoped bearer credential", "description": "Returns safe key prefixes, suffixes, scopes, lifecycle timestamps, and bindings. Raw keys and stored hashes are never returned.", "security": [ { "BearerAuth": [ "identity.developer.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/DeveloperApiKeys200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/developer/audit-events": { "get": { "tags": [ "Developer" ], "summary": "List owner-scoped audit and security activity", "description": "Returns bounded cursor-paginated activity where the authenticated user is the actor or subject, plus that user's security events. Metadata, secrets, tokens, payloads, and provider response bodies are never returned.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/api/v1/developer/audit-events": { "get": { "tags": [ "Developer" ], "summary": "List owner-scoped audit and security activity with a bearer credential", "description": "Returns safe activity records for the bearer credential owner with bounded opaque cursors. Metadata, secrets, tokens, payloads, and provider response bodies are never returned.", "security": [ { "BearerAuth": [ "identity.developer.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/DeveloperAuditEvents200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/developer/api-keys/revoke": { "post": { "tags": [ "Developer" ], "summary": "Revoke an owned API key", "description": "Requires recent passkey step-up. An optional Idempotency-Key makes a retry after a lost response safe; replay returns no credential material.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/developer/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List owned webhook subscriptions with cursor pagination", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a signed outbound webhook subscription", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "409": { "$ref": "#/components/responses/Json409" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/v1/developer/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List owned webhook subscriptions with a scoped bearer credential", "description": "Returns safe webhook metadata and parsed event names with bounded opaque cursors. Signing secrets, hashes, and encrypted custody material are never returned.", "security": [ { "BearerAuth": [ "identity.developer.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/DeveloperWebhooks200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/developer/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List owned webhook delivery metadata with cursor pagination", "description": "Returns status and safe failure classifications without payloads, secrets, or destination response bodies. Results use stable descending created_at and ID order.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "webhook_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/api/v1/developer/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List owned webhook delivery metadata with a scoped bearer credential", "description": "Returns safe delivery status and provider failure classifications with bounded opaque cursors. Payloads, signing secrets, and destination response bodies are never returned.", "security": [ { "BearerAuth": [ "identity.developer.read" ] } ], "parameters": [ { "name": "webhook_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "$ref": "#/components/responses/DeveloperWebhookDeliveries200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/api/developer/webhooks/test": { "post": { "tags": [ "Webhooks" ], "summary": "Deliver a signed test event", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "409": { "$ref": "#/components/responses/Json409" }, "502": { "$ref": "#/components/responses/Json502" } } } }, "/api/v1/developer/webhooks/test": { "post": { "tags": [ "Webhooks" ], "summary": "Deliver a signed test event with a scoped API key", "description": "Server-to-server mutation for CLI and automation. Requires an API key with identity.webhooks.test and an Idempotency-Key. The event payload and destination response body are never returned.", "security": [ { "BearerAuth": [ "identity.webhooks.test" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "202": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "409": { "$ref": "#/components/responses/Json409" }, "502": { "$ref": "#/components/responses/Json502" } } } }, "/api/developer/webhooks/deliveries/process": { "post": { "tags": [ "Webhooks" ], "summary": "Queue due webhook deliveries for the authenticated owner", "description": "Requires an authenticated session with recent passkey step-up. Only applications owned by the current user are processed.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "202": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/api/developer/webhooks/deliveries/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Queue an owned failed webhook delivery for retry", "description": "Requires an authenticated session with recent passkey step-up. Retry is bounded and returns 202 without destination response data.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "202": { "$ref": "#/components/responses/Json200" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/developer/webhooks/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate an outbound webhook signing secret safely for retries", "description": "Requires recent passkey step-up. Idempotency-Key prevents duplicate rotations after a lost response; replay returns no secret.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/developer/webhooks/disable": { "post": { "tags": [ "Webhooks" ], "summary": "Disable an owned webhook subscription", "description": "Requires recent passkey step-up. An optional Idempotency-Key makes a retry after a lost response safe; the signing secret is never returned.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/webhooks/resend": { "post": { "tags": [ "Webhooks" ], "summary": "Receive signed Resend delivery events", "description": "Validates Svix headers and the raw request body before parsing. Raw payloads are not persisted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" } } } }, "/oauth/authorize": { "post": { "tags": [ "OAuth/OIDC" ], "summary": "Issue an authorization code after session consent", "description": "Requires an authenticated Lucion session, exact Origin, CSRF proof, exact registered redirect (with the RFC 8252 loopback-port exception for native callbacks), state, and PKCE S256. MCP authorization is additionally bound to the MCP resource and explicit consent.", "security": [ { "SessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "403": { "$ref": "#/components/responses/Json403" } } } }, "/oauth/authorize/context": { "get": { "tags": [ "OAuth/OIDC" ], "summary": "Validate an OAuth request before rendering consent", "description": "Validates the client, redirect, scope, state, PKCE S256 challenge, and (for MCP) resource before showing customer-facing consent details.", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "response_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "scope", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "S256" ] } }, { "name": "resource", "in": "query", "required": false, "schema": { "type": "string", "format": "uri" } } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/oauth/register": { "post": { "tags": [ "OAuth/OIDC" ], "summary": "Dynamically register a public assistant OAuth client", "description": "Rate-limited registration accepts HTTPS web callbacks or native loopback HTTP callbacks. Client secrets are not issued; authorization code + PKCE is required.", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "429": { "$ref": "#/components/responses/Json429" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/oauth/token": { "post": { "tags": [ "OAuth/OIDC" ], "summary": "Exchange an authorization code or rotating refresh token", "description": "MCP grants require the exact resource https://identity.lucionglobal.com/mcp on authorization, code exchange, and refresh. Refresh tokens rotate; reuse revokes the family.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/oauth/userinfo": { "get": { "tags": [ "OAuth/OIDC" ], "summary": "Return scoped OIDC claims", "security": [ { "BearerAuth": [ "openid" ] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/oauth/revoke": { "post": { "tags": [ "OAuth/OIDC" ], "summary": "Revoke an OAuth token and its refresh-token family", "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/mcp": { "post": { "tags": [ "MCP" ], "summary": "Call Lucion Identity MCP tools with a resource-bound OAuth bearer", "description": "Requires identity.api_keys.create and the MCP audience. create_api_key accepts only explicitly requested read-only key scopes, 7/30/90-day expiry, and an idempotency key. The key is returned once in assistant tool output and may remain in conversation history.", "security": [ { "BearerAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "413": { "description": "JSON-RPC body exceeded the 32 KiB request limit" }, "415": { "description": "Request must use application/json" }, "429": { "$ref": "#/components/responses/Json429" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/.well-known/oauth-protected-resource/mcp": { "get": { "tags": [ "OAuth/OIDC", "MCP" ], "summary": "Protected-resource metadata for the MCP server", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/.well-known/openid-configuration": { "get": { "tags": [ "OAuth/OIDC" ], "summary": "OIDC discovery metadata", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "OAuth/OIDC" ], "summary": "OAuth authorization-server metadata", "responses": { "200": { "$ref": "#/components/responses/Json200" } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "OAuth/OIDC" ], "summary": "Public OIDC signing keys", "responses": { "200": { "$ref": "#/components/responses/Json200" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/scim/v2/Users": { "get": { "tags": [ "SCIM" ], "summary": "List active users in the token's organization", "description": "Supports bounded startIndex/count pagination and exact userName or externalId equality filters.", "security": [ { "ScimBearer": [] } ], "parameters": [ { "name": "startIndex", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 100 } }, { "name": "filter", "in": "query", "required": false, "description": "Supported forms: userName eq \"email\" or externalId eq \"value\".", "schema": { "type": "string", "maxLength": 320 } } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "503": { "$ref": "#/components/responses/Json503" } } }, "post": { "tags": [ "SCIM" ], "summary": "Provision a user into the SCIM token's organization", "description": "Creates an organization-scoped SCIM mapping and membership. Email ownership is immutable and no session or authentication privilege is issued. Reuse the same Idempotency-Key after a timeout; a changed request under the same key is rejected.", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true, "maxProperties": 50 } }, "application/json": { "schema": { "type": "object", "additionalProperties": true, "maxProperties": 50 } } } }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "409": { "$ref": "#/components/responses/Json409" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/scim/v2/Users/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "get": { "tags": [ "SCIM" ], "summary": "Read one organization-scoped SCIM user", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "304": { "description": "Resource has not changed", "headers": { "ETag": { "$ref": "#/components/headers/EntityTag" } } }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" } } }, "put": { "tags": [ "SCIM" ], "summary": "Replace one organization-scoped SCIM user", "description": "Replaces displayName and active state. userName/email ownership is immutable; externalId is immutable once assigned. If-Match prevents overwriting a newer directory write; reuse the same Idempotency-Key after a timeout.", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true, "maxProperties": 50 } }, "application/json": { "schema": { "type": "object", "additionalProperties": true, "maxProperties": 50 } } } }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" }, "412": { "$ref": "#/components/responses/Json412" } } }, "patch": { "tags": [ "SCIM" ], "summary": "Patch one organization-scoped SCIM user", "description": "Supports up to 20 add/replace/remove operations for active and displayName. Email ownership changes are rejected. If-Match prevents overwriting a newer directory write; reuse the same Idempotency-Key after a timeout.", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true, "maxProperties": 50 } }, "application/json": { "schema": { "type": "object", "additionalProperties": true, "maxProperties": 50 } } } }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" }, "412": { "$ref": "#/components/responses/Json412" } } }, "delete": { "tags": [ "SCIM" ], "summary": "Deprovision one organization-scoped SCIM user", "description": "Suspends only the organization membership and retains the underlying Lucion identity and credentials. If-Match prevents deleting a resource changed since it was read; reuse the same Idempotency-Key after a timeout.", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "User deprovisioned" }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" }, "412": { "$ref": "#/components/responses/Json412" } } } }, "/scim/v2/ServiceProviderConfig": { "get": { "tags": [ "SCIM" ], "summary": "Read SCIM service capabilities", "description": "Advertises PATCH and ETag support. Resource reads return an opaque ETag and meta.version; If-None-Match supports conditional GET and If-Match protects updates and deprovisioning from stale writers.", "security": [ { "ScimBearer": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/scim/v2/ResourceTypes": { "get": { "tags": [ "SCIM" ], "summary": "Read SCIM resource-type metadata", "security": [ { "ScimBearer": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" } } } }, "/scim/v2/Schemas/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "get": { "tags": [ "SCIM" ], "summary": "Read one SCIM resource schema", "security": [ { "ScimBearer": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" } } } }, "/scim/v2/Groups": { "get": { "tags": [ "SCIM" ], "summary": "List organization groups", "security": [ { "ScimBearer": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" } } }, "post": { "tags": [ "SCIM" ], "summary": "Provision an organization group", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "201": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/scim/v2/Groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "get": { "tags": [ "SCIM" ], "summary": "Read an organization group", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "304": { "description": "Resource has not changed", "headers": { "ETag": { "$ref": "#/components/headers/EntityTag" } } }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" } } }, "put": { "tags": [ "SCIM" ], "summary": "Replace an organization group", "description": "Replaces displayName and the active-user membership set. If-Match prevents overwriting a newer directory write. Reuse the same Idempotency-Key after a timeout; a changed request under the same key is rejected.", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" }, "412": { "$ref": "#/components/responses/Json412" } } }, "patch": { "tags": [ "SCIM" ], "summary": "Patch an organization group", "description": "Updates displayName and membership operations. If-Match prevents overwriting a newer directory write. Reuse the same Idempotency-Key after a timeout; a changed request under the same key is rejected.", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" }, "412": { "$ref": "#/components/responses/Json412" } } }, "delete": { "tags": [ "SCIM" ], "summary": "Deprovision an organization group", "description": "Removes only the group and its group memberships. If-Match prevents deleting a resource changed since it was read. Reuse the same Idempotency-Key after a timeout; a changed request under the same key is rejected.", "security": [ { "ScimBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Group removed" }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" }, "412": { "$ref": "#/components/responses/Json412" } } } }, "/api/developer/applications/{application_id}": { "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "patch": { "tags": [ "Developer" ], "summary": "Edit an owned application", "description": "Requires an authenticated Lucion session, exact Origin, CSRF proof, recent step-up, and Idempotency-Key. Only name, description, HTTPS homepage_url, exact redirect_uris, and scopes may change; the client ID and client type are immutable. Returns metadata only and never returns a client secret.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" } } }, "delete": { "tags": [ "Developer" ], "summary": "Disable and delete an owned application", "description": "Requires an authenticated Lucion session, exact Origin, CSRF proof, recent step-up, and Idempotency-Key. Retains an audit tombstone and revokes the application's client secrets, API keys, OAuth grants/tokens, consents, webhooks, and delegations; it does not delete users. A completed replay returns 409 without secret material.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/developer/applications/{application_id}/rotate-secret": { "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "post": { "tags": [ "Developer" ], "summary": "Rotate an owned confidential OIDC client secret", "description": "Requires an authenticated Lucion session, exact Origin, CSRF proof, recent step-up, and Idempotency-Key. The JSON request object must be empty. Revokes the previous secret and returns the replacement once; only its hash verifier is stored. A replay returns 409 and never returns the secret again.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/Json" }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "403": { "$ref": "#/components/responses/Json403" }, "404": { "$ref": "#/components/responses/Json404" }, "409": { "$ref": "#/components/responses/Json409" } } } }, "/api/developer/applications/{application_id}/certification/status": { "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{1,127}$" } } ], "get": { "tags": [ "Developer" ], "summary": "Read an owned application certification status", "description": "Returns safe signed certification metadata and registered scopes. The review evidence and provider decision token are never returned. Unsubmitted apps report NOT_SUBMITTED; the review service must issue approvals.", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/internal/integration-decisions": { "post": { "tags": [ "Developer" ], "summary": "Consume a signed Lucion Developer certification decision", "description": "Server-to-server only. Requires a short-lived Ed25519-signed JWT from the configured issuer and audience. Decisions bind application, client, environment, policy version, artifact, scopes, expiry, reviewer, sequence, and replay identifier. A suspension, revocation, or rejection revokes outstanding app tokens.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "decision_jwt" ], "properties": { "decision_jwt": { "type": "string", "maxLength": 16384 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Json200" }, "400": { "$ref": "#/components/responses/Json400" }, "401": { "$ref": "#/components/responses/Json401" }, "409": { "$ref": "#/components/responses/Json409" }, "503": { "$ref": "#/components/responses/Json503" } } } }, "/internal/client-trust/{client_id}": { "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 4, "maxLength": 200 } } ], "get": { "tags": [ "Developer" ], "summary": "Read the current application trust decision for a Lucion resource server", "description": "Protected service-to-service lookup using the configured trust API bearer secret. Returns only current app status, policy version, expiry, and allowed scopes. Responses are no-store; resource servers must still validate token issuer, signature, audience, scope, and expiry.", "security": [ { "TrustServiceBearer": [] } ], "responses": { "200": { "$ref": "#/components/responses/Json200" }, "401": { "$ref": "#/components/responses/Json401" }, "404": { "$ref": "#/components/responses/Json404" }, "429": { "$ref": "#/components/responses/Json429" }, "503": { "$ref": "#/components/responses/Json503" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "OAuth2 access token or lid_live API key" }, "SessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-lid_session", "description": "Secure, HttpOnly, SameSite=Lax session cookie; mutation requests also require X-Lucion-CSRF and exact Origin." }, "ScimBearer": { "type": "http", "scheme": "bearer", "description": "SCIM token bound to one organization; never use a user session or API key." }, "TrustServiceBearer": { "type": "http", "scheme": "bearer", "description": "Server-only trust lookup credential; never send from browser clients." } }, "parameters": { "PageLimit": { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return; defaults to 100 and is bounded to 1\u2013100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, "PageCursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque continuation token from next_cursor. Do not parse or manufacture it.", "schema": { "type": "string", "minLength": 16, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "16\u2013128 character client token. The server stores only a namespace-scoped hash. Reusing a key with a different request returns 409; one-time secrets are not replayed.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } }, "IfMatch": { "name": "If-Match", "in": "header", "required": false, "description": "Strong SCIM entity tag returned by a resource read. Use * only when an existing resource may be modified regardless of its current version. A stale tag returns 412 without changing data.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "description": "Entity tag returned by a previous resource read. A matching tag returns 304 without a resource body; weak tags are accepted for conditional reads.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } }, "requestBodies": { "Json": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "maxProperties": 50 } } } } }, "responses": { "Json200": { "description": "JSON response", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "DeveloperApplications200": { "description": "Owner-scoped application metadata page", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApplicationsResponse" }, "example": { "applications": [ { "id": "app_REDACTED", "name": "Example app", "client_id": "lid_client_REDACTED", "application_type": "public", "status": "active", "description": null, "homepage_url": "https://example.com", "token_endpoint_auth_method": "none", "created_at": "2026-09-06T00:00:00.000Z", "updated_at": "2026-09-06T00:00:00.000Z" } ], "has_more": false, "next_cursor": null, "authentication": "api_key", "scopes": [ "identity.developer.read" ] } } } }, "DeveloperApiKeys200": { "description": "Owner-scoped API-key metadata page", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiKeysResponse" }, "example": { "api_keys": [ { "id": "key_REDACTED", "name": "Production integration", "key_prefix": "lid_live_", "key_suffix": "REDACTED", "scopes": [ "identity.developer.read" ], "expires_at": null, "created_at": "2026-09-06T00:00:00.000Z", "last_used_at": null, "revoked_at": null, "application_id": "app_REDACTED", "organization_id": null } ], "has_more": false, "next_cursor": null, "authentication": "api_key", "scopes": [ "identity.developer.read" ] } } } }, "DeveloperAuditEvents200": { "description": "Owner-scoped audit activity page", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAuditEventsResponse" }, "example": { "audit_events": [ { "id": "aud_REDACTED", "occurred_at": "2026-09-06T00:00:00.000Z", "actor_type": "user", "actor_id": "usr_REDACTED", "subject_user_id": "usr_REDACTED", "organization_id": null, "application_id": "app_REDACTED", "action": "developer.read", "scope_key": "identity.developer.read", "resource_type": "application", "resource_id": "app_REDACTED", "outcome": "allowed" } ], "has_more": false, "next_cursor": null, "authentication": "api_key", "scopes": [ "identity.developer.read" ] } } } }, "DeveloperWebhooks200": { "description": "Owner-scoped webhook subscription page", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperWebhooksResponse" }, "example": { "webhooks": [ { "id": "wh_REDACTED", "application_id": "app_REDACTED", "endpoint_url": "https://example.com/hooks", "events": [ "identity.user.created" ], "status": "active", "created_at": "2026-09-06T00:00:00.000Z", "updated_at": "2026-09-06T00:00:00.000Z", "last_success_at": null, "last_failure_at": null } ], "has_more": false, "next_cursor": null, "authentication": "api_key", "scopes": [ "identity.developer.read" ] } } } }, "DeveloperWebhookDeliveries200": { "description": "Owner-scoped webhook delivery metadata page", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperWebhookDeliveriesResponse" }, "example": { "deliveries": [ { "id": "wd_REDACTED", "event_id": "evt_REDACTED", "event_type": "identity.user.created", "status": "delivered", "attempts": 1, "next_attempt_at": null, "last_error_code": null, "response_status": 204, "created_at": "2026-09-06T00:00:00.000Z", "updated_at": "2026-09-06T00:00:00.000Z", "delivered_at": "2026-09-06T00:00:01.000Z" } ], "has_more": false, "next_cursor": null, "authentication": "api_key", "scopes": [ "identity.developer.read" ] } } } }, "Json400": { "description": "Invalid request or verification failure", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Json401": { "description": "Authentication required or token invalid", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Json403": { "description": "Origin, CSRF, tenant, or scope boundary denied", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Json404": { "description": "Owned resource not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Json409": { "description": "Replay or resource conflict", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Json412": { "description": "SCIM resource changed since the supplied If-Match value", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "ETag": { "$ref": "#/components/headers/EntityTag" } }, "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } } }, "Json429": { "description": "Authentication-risk rate limit exceeded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Json502": { "description": "Bounded outbound webhook delivery failed", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Json503": { "description": "Capability or dependency is gated/unavailable", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Json406": { "description": "Requested API version is not supported", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Lucion-Identity-Version": { "$ref": "#/components/headers/ReleaseVersion" }, "X-Lucion-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-Lucion-Supported-API-Versions": { "$ref": "#/components/headers/SupportedApiVersions" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "headers": { "RequestId": { "description": "Server-generated correlation identifier; safe to quote in support requests.", "schema": { "type": "string", "minLength": 16, "maxLength": 32 } }, "ReleaseVersion": { "description": "Deployed Lucion Identity release fingerprint.", "schema": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" } }, "ApiVersion": { "description": "Current version of the route family, such as v1 or scim-2.0.", "schema": { "type": "string", "pattern": "^(v[0-9]+|scim-[0-9]+\\.[0-9]+)$" } }, "ApiLifecycle": { "description": "Lifecycle state of the advertised API version.", "schema": { "type": "string", "enum": [ "current", "deprecated" ] } }, "SupportedApiVersions": { "description": "Comma-separated supported versions for the route family.", "schema": { "type": "string", "minLength": 2, "maxLength": 64 } }, "EntityTag": { "description": "Opaque strong SCIM resource version used for conditional reads and stale-write protection.", "schema": { "type": "string", "pattern": "^\"[A-Za-z0-9_-]{3,128}\"$" } }, "RateLimitLimit": { "description": "Maximum attempts in the endpoint-specific authentication-risk window.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimitRemaining": { "description": "Remaining attempts in the current endpoint-specific window.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimitReset": { "description": "Seconds until the endpoint-specific window resets.", "schema": { "type": "integer", "minimum": 0 } }, "RetryAfter": { "description": "Seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } }, "schemas": { "JsonObject": { "type": "object", "additionalProperties": true }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Stable non-secret error code." }, "retry_after_seconds": { "type": "integer" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "failure_code": { "type": "string" }, "supported_versions": { "type": "array", "items": { "type": "string" } }, "current_version": { "type": "string" }, "documentation": { "type": "string" } }, "additionalProperties": false }, "ScimError": { "type": "object", "required": [ "schemas", "status", "detail" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "scimType": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": true }, "DeveloperApplication": { "type": "object", "required": [ "allowed_emails", "application_type", "client_id", "created_at", "description", "homepage_url", "id", "name", "status", "token_endpoint_auth_method", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "client_id": { "type": "string" }, "application_type": { "type": "string", "enum": [ "public", "confidential", "service" ] }, "status": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "homepage_url": { "type": [ "string", "null" ], "format": "uri" }, "token_endpoint_auth_method": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "allowed_emails": { "type": "array", "maxItems": 100, "items": { "type": "string", "format": "email" } } }, "additionalProperties": false }, "DeveloperApiKey": { "type": "object", "required": [ "id", "name", "key_prefix", "key_suffix", "scopes", "expires_at", "created_at", "last_used_at", "revoked_at", "application_id", "organization_id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "key_suffix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "application_id": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "DeveloperAuditEvent": { "type": "object", "required": [ "id", "occurred_at", "actor_type", "actor_id", "action", "resource_type", "resource_id", "outcome" ], "properties": { "id": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "subject_user_id": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "string", "null" ] }, "application_id": { "type": [ "string", "null" ] }, "action": { "type": "string" }, "scope_key": { "type": [ "string", "null" ] }, "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "outcome": { "type": "string" } }, "additionalProperties": false }, "DeveloperWebhook": { "type": "object", "required": [ "id", "application_id", "endpoint_url", "events", "status", "created_at", "updated_at", "last_success_at", "last_failure_at" ], "properties": { "id": { "type": "string" }, "application_id": { "type": "string" }, "endpoint_url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "DeveloperWebhookDelivery": { "type": "object", "required": [ "id", "event_id", "event_type", "status", "attempts", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer", "minimum": 0 }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error_code": { "type": [ "string", "null" ] }, "response_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "DeveloperApplicationsResponse": { "type": "object", "required": [ "applications", "has_more", "next_cursor", "authentication", "scopes" ], "properties": { "applications": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperApplication" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "authentication": { "type": "string", "enum": [ "api_key", "oauth" ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "DeveloperApiKeysResponse": { "type": "object", "required": [ "api_keys", "has_more", "next_cursor", "authentication", "scopes" ], "properties": { "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperApiKey" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "authentication": { "type": "string", "enum": [ "api_key", "oauth" ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "DeveloperAuditEventsResponse": { "type": "object", "required": [ "audit_events", "has_more", "next_cursor", "authentication", "scopes" ], "properties": { "audit_events": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperAuditEvent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "authentication": { "type": "string", "enum": [ "api_key", "oauth" ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "DeveloperWebhooksResponse": { "type": "object", "required": [ "webhooks", "has_more", "next_cursor", "authentication", "scopes" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperWebhook" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "authentication": { "type": "string", "enum": [ "api_key", "oauth" ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "DeveloperWebhookDeliveriesResponse": { "type": "object", "required": [ "deliveries", "has_more", "next_cursor", "authentication", "scopes" ], "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperWebhookDelivery" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "authentication": { "type": "string", "enum": [ "api_key", "oauth" ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } }, "version": "6.6.6" }