{ "openapi": "3.1.0", "info": { "title": "SigID Public API", "description": "Public integrator surface for third-party apps, agents, and wallets: OIDC discovery, OAuth 2.1 token endpoints, OpenID4VC issuance and presentation, health probes, feature capabilities, agent authentication, and public buyer commerce (payment links /pay/{token}, checkout sessions, x402). For hosted login prefer @sigid/start (cdn.sigid.org/v1/sigid.js). Merchant commerce admin APIs and Dashboard control-plane routes are intentionally omitted; see docs.sigid.org/developers/commerce.md.", "license": { "name": "MIT", "identifier": "MIT" }, "version": "2.2.1" }, "paths": { "/.well-known/jwks.json": { "get": { "tags": [ "Well-Known" ], "summary": "GET /.well-known/jwks.json – JSON Web Key Set.\nAlways returns the canonical issuer JWKS, including every verifiable key\nthat can sign tokens for that issuer. Public discovery output must not vary\nwith any optional `TenantContext` that middleware may have inserted.", "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "jwks", "responses": { "200": { "description": "JSON Web Key Set", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Failed to build JWKS", "content": { "application/json": { "schema": {} } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/.well-known/jwt-vc-issuer": { "get": { "tags": [ "Well-Known" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "sd_jwt_vc_issuer_metadata", "responses": { "200": { "description": "SD-JWT VC issuer verification metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdJwtVcIssuerMetadata" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/.well-known/jwt-vc-issuer/credential-issuers/{tenant_slug}": { "get": { "tags": [ "Well-Known" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "tenant_sd_jwt_vc_issuer_metadata", "parameters": [ { "name": "tenant_slug", "in": "path", "description": "Tenant issuer slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant SD-JWT VC issuer verification metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdJwtVcIssuerMetadata" } } } }, "404": { "description": "Tenant issuer is not enabled" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/.well-known/openid-configuration": { "get": { "tags": [ "Well-Known" ], "summary": "GET /.well-known/openid-configuration – OIDC discovery document.", "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "openid_configuration", "responses": { "200": { "description": "OIDC discovery document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcDiscovery" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/.well-known/openid-credential-issuer": { "get": { "tags": [ "Well-Known" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "credential_issuer_metadata", "responses": { "200": { "description": "OpenID credential issuer metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialIssuerMetadata" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/.well-known/openid-credential-issuer/credential-issuers/{tenant_slug}": { "get": { "tags": [ "Well-Known" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "tenant_credential_issuer_metadata", "parameters": [ { "name": "tenant_slug", "in": "path", "description": "Tenant issuer slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant OpenID credential issuer metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialIssuerMetadata" } } } }, "404": { "description": "Tenant issuer is not enabled" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/agents/auth/challenge": { "post": { "tags": [ "Agent" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "create_challenge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeRequest" } } }, "required": true }, "responses": { "200": { "description": "Challenge created" }, "400": { "description": "Invalid request" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/agents/auth/verify": { "post": { "tags": [ "Agent" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "verify_challenge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Tokens issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "Invalid request or verification failed" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/agents/workspace/bootstrap": { "get": { "tags": [ "Agent" ], "summary": "Discover the issuer and tenant UUID to sign before starting workspace PoW.\nNo existing tenant credentials are needed. This does not create resources.", "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "bootstrap_metadata", "responses": { "200": { "description": "Public control-plane key-proof binding; no credentials required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceBootstrapMetadata" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/capabilities": { "get": { "tags": [ "Capabilities" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "get_capabilities", "responses": { "200": { "description": "Currently enabled server capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/public/commerce/checkout-sessions": { "post": { "tags": [ "Commerce" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "create_checkout_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Checkout session created with hosted checkout_url" }, "400": { "description": "Invalid input or redirect host not allowlisted" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/public/commerce/fulfillment/{charge_id}": { "get": { "tags": [ "Commerce" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "get_fulfillment", "parameters": [ { "name": "charge_id", "in": "path", "description": "Charge id from a commerce webhook event", "required": true, "schema": { "type": "string" } }, { "name": "X-SigID-Fulfillment-Secret", "in": "header", "description": "Active webhook signing secret for a subscription scoped to commerce.payment.* lifecycle events", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fulfillment detail for the charge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceFulfillmentView" } } } }, "401": { "description": "Missing or invalid fulfillment secret" }, "404": { "description": "Charge not found in this tenant" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/public/commerce/payment-links/{payment_link_token}/checkout": { "post": { "tags": [ "Commerce" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "create_payment_link_checkout", "parameters": [ { "name": "payment_link_token", "in": "path", "description": "Public payment-link token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkCheckoutRequest" } } }, "required": true }, "responses": { "200": { "description": "Checkout session created for the payment link" }, "404": { "description": "Payment link not found or inactive" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/public/commerce/payment-links/{payment_link_token}/x402": { "get": { "tags": [ "Commerce" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "get_x402_payment_link", "parameters": [ { "name": "payment_link_token", "in": "path", "description": "Public payment-link token", "required": true, "schema": { "type": "string" } }, { "name": "buyer_country", "in": "query", "description": "Buyer jurisdiction country (required)", "required": true, "schema": { "type": "string" } }, { "name": "buyer_region", "in": "query", "description": "Buyer jurisdiction region (required)", "required": true, "schema": { "type": "string" } } ], "responses": { "402": { "description": "Payment Required challenge" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Commerce" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "settle_x402_payment_link", "parameters": [ { "name": "payment_link_token", "in": "path", "description": "Public payment-link token", "required": true, "schema": { "type": "string" } }, { "name": "buyer_country", "in": "query", "description": "Buyer jurisdiction country (required)", "required": true, "schema": { "type": "string" } }, { "name": "buyer_region", "in": "query", "description": "Buyer jurisdiction region (required)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "x402 payment settled" }, "402": { "description": "Rejected payment" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/public/commerce/subscription-checkout-sessions": { "post": { "tags": [ "Commerce" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "create_subscription_checkout_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionCheckoutSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Recurring subscription checkout session created" }, "400": { "description": "Invalid recurring price, buyer, or redirect" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/credential-issuers/{tenant_slug}/.well-known/jwks.json": { "get": { "tags": [ "Well-Known" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "tenant_issuer_jwks", "parameters": [ { "name": "tenant_slug", "in": "path", "description": "Tenant issuer slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant issuer JSON Web Key Set", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Tenant issuer is not enabled" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/health/live": { "get": { "tags": [ "Health" ], "summary": "Liveness probe – always returns 200 if the process is running.", "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "liveness", "responses": { "200": { "description": "Service is alive", "content": { "application/json": { "schema": {} } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/health/ready": { "get": { "tags": [ "Health" ], "summary": "Readiness probe – returns 200 if the database is reachable, 503 otherwise.", "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "readiness", "responses": { "200": { "description": "Service is ready", "content": { "application/json": { "schema": {} } } }, "503": { "description": "Service is not ready", "content": { "application/json": { "schema": {} } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/health/startup": { "get": { "tags": [ "Health" ], "summary": "Startup probe – returns 200 when migrations and core startup config are loaded.", "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "startup", "responses": { "200": { "description": "Service has started", "content": { "application/json": { "schema": {} } } }, "503": { "description": "Service is starting", "content": { "application/json": { "schema": {} } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oauth/authorize": { "get": { "tags": [ "OAuth" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "authorize", "parameters": [ { "name": "response_type", "in": "query", "description": "Must be 'code'", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "OAuth client ID", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "description": "Redirect URI", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "Requested scopes", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "CSRF state parameter", "required": false, "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "description": "PKCE code challenge", "required": false, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "description": "PKCE method (S256)", "required": false, "schema": { "type": "string" } }, { "name": "nonce", "in": "query", "description": "OIDC nonce", "required": false, "schema": { "type": "string" } }, { "name": "prompt", "in": "query", "description": "Prompt mode (none, login, consent)", "required": false, "schema": { "type": "string" } }, { "name": "max_age", "in": "query", "description": "Max authentication age in seconds", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "tenant_id", "in": "query", "description": "Shared-host tenant UUID; mutually exclusive with tenant_slug", "required": false, "schema": { "type": "string" } }, { "name": "tenant_slug", "in": "query", "description": "Shared-host canonical tenant slug; mutually exclusive with tenant_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Login or consent page HTML" }, "302": { "description": "Redirect to client with auth code" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "OAuth" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "authorize_post", "requestBody": { "description": "Authorization request parameters in form serialization", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Login or consent page HTML" }, "302": { "description": "Redirect to client with auth code" }, "400": { "description": "Invalid request parameters" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oauth/end-session": { "get": { "tags": [ "OAuth" ], "summary": "GET /oauth/end-session – OIDC RP-Initiated Logout.", "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "end_session", "parameters": [ { "name": "id_token_hint", "in": "query", "description": "Previously issued ID token", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "Client identifier", "required": false, "schema": { "type": "string" } }, { "name": "post_logout_redirect_uri", "in": "query", "description": "URI to redirect after logout", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Opaque value echoed back", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Logout complete" }, "302": { "description": "Redirected after logout" }, "400": { "description": "Invalid request" }, "500": { "description": "Internal error" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oauth/introspect": { "post": { "tags": [ "OAuth" ], "summary": "POST /oauth/introspect – RFC 7662 token introspection.", "description": "**Idempotency:** Default idempotent. The server derives idempotency from the exact request even when `Idempotency-Key` is omitted.", "operationId": "introspect_endpoint", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/IntrospectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Token introspection response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntrospectionResponse" } } } }, "401": { "description": "Invalid client authentication" }, "500": { "description": "Internal error" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oauth/par": { "post": { "tags": [ "OAuth" ], "summary": "POST /oauth/par – RFC 9126 Pushed Authorization Request.", "description": "Stores a validated authorization request server-side and returns a short\n`request_uri` reference for the browser-facing `/oauth/authorize` request.\n\n**Idempotency:** Default idempotent. The server derives idempotency from the exact request and binds client-authenticated replays to the same `Authorization` header when one is present.", "operationId": "pushed_authorization_request", "requestBody": { "description": "Authorization request parameters plus client authentication", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } }, "required": true }, "responses": { "201": { "description": "Pushed authorization request accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushedAuthorizationResponse" } } } }, "400": { "description": "Invalid authorization request" }, "401": { "description": "Invalid client authentication" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oauth/register": { "post": { "tags": [ "OAuth" ], "summary": "POST /oauth/register – RFC 7591 Dynamic Client Registration.", "description": "**Idempotency:** Opt-in via `Idempotency-Key`. Keyed retries are replay-safe: they never create a second client. The registration response carries a one-time credential (`client_secret`, `registration_access_token`) that is returned only to the first caller; a matching keyed retry after completion receives `409 credential_already_issued` instead of re-issuing or replaying the credential. Requests without an `Idempotency-Key` always execute and are not deduplicated.", "operationId": "dynamic_client_registration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRegistrationRequest" } } }, "required": true }, "responses": { "201": { "description": "Client registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRegistrationResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing initial access token" }, "403": { "description": "Dynamic registration disabled" }, "409": { "description": "Concurrent request with the same Idempotency-Key in progress, or the once-only registration credential was already issued to the first caller and cannot be replayed" }, "500": { "description": "Internal error" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oauth/register/{client_id}": { "get": { "tags": [ "OAuth" ], "summary": "GET /oauth/register/{client_id} – RFC 7592 Client Read.", "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "client_read", "parameters": [ { "name": "client_id", "in": "path", "description": "The client_id of the registered client", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientReadResponse" } } } }, "401": { "description": "Invalid or missing registration_access_token" }, "500": { "description": "Internal error" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oauth/revoke": { "post": { "tags": [ "OAuth" ], "summary": "POST /oauth/revoke – RFC 7009 token revocation.\nPer RFC 7009, always returns 200 regardless of whether the token was valid.\nAuthenticated clients can only revoke their own tokens.", "description": "**Idempotency:** Default idempotent. The server derives idempotency from the exact request even when `Idempotency-Key` is omitted.", "operationId": "revoke_endpoint", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RevocationRequest" } } }, "required": true }, "responses": { "200": { "description": "Token revoked or was invalid" }, "401": { "description": "Invalid client authentication" }, "500": { "description": "Internal error" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oauth/token": { "post": { "tags": [ "OAuth" ], "summary": "POST /oauth/token – token endpoint handling all grant types.\nSupports authorization_code, client_credentials, device_code, refresh_token, and token exchange grants.", "description": "**Idempotency:** Opt-in via `Idempotency-Key`. Retries are replay-safe only when the same header is sent with the same request parameters.", "operationId": "token_endpoint", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid client authentication" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oid4vci/credential": { "post": { "tags": [ "OpenID4VC" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "issue_credential", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRequest" } } }, "required": true }, "responses": { "200": { "description": "Issued holder-bound SD-JWT VC", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialResponse" } } } }, "400": { "description": "Invalid credential request or proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolErrorResponse" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolErrorResponse" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearer_auth": [] }, { "dpop_auth": [], "dpop_proof": [] } ] } }, "/oid4vci/credential-offers": { "post": { "tags": [ "OpenID4VC" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "create_credential_offer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialOfferRequest" } } }, "required": true }, "responses": { "200": { "description": "Cross-device credential offer URI, SVG QR code, and separately delivered transaction code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialOfferCreated" } } } }, "400": { "description": "Credential offer is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolErrorResponse" } } } }, "401": { "description": "Missing or invalid access token, or a sender-constrained (DPoP-bound) token presented as a plain Bearer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolErrorResponse" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearer_auth": [] }, { "dpop_auth": [], "dpop_proof": [] } ] } }, "/oid4vci/nonce": { "post": { "tags": [ "OpenID4VC" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "create_nonce", "responses": { "200": { "description": "Fresh single-use credential proof nonce", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NonceResponse" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oid4vp/direct_post": { "post": { "tags": [ "OpenID4VC" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "direct_post", "parameters": [ { "name": "request_uri_state", "in": "query", "description": "State bound into the response URI", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DirectPostForm" } } }, "required": true }, "responses": { "200": { "description": "Presentation or wallet error accepted for browser-bound completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectPostAccepted" } } } }, "400": { "description": "Invalid, untrusted, or replayed presentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolErrorResponse" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oid4vp/presentations": { "post": { "tags": [ "OpenID4VC" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "create_presentation_request", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePresentationRequest" } } }, "required": true }, "responses": { "200": { "description": "OID4VP wallet request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationRequestCreated" } } } }, "400": { "description": "Invalid hosted authorization transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolErrorResponse" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/oid4vp/presentations/complete": { "post": { "tags": [ "OpenID4VC" ], "description": "**Idempotency:** Not idempotent. Retrying the same request can start a new flow step, rotate credentials, or consume a one-time token or challenge.", "operationId": "complete_presentation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletePresentationRequest" } } }, "required": true }, "responses": { "200": { "description": "Presentation mapped into the hosted OIDC flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletePresentationResponse" } } } }, "400": { "description": "Presentation is incomplete or browser binding failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolErrorResponse" } } } }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/pay/{payment_link_token}": { "get": { "tags": [ "Commerce" ], "description": "**Idempotency:** Default idempotent. Repeating the same request does not create an additional side effect.", "operationId": "redirect_payment_link", "parameters": [ { "name": "payment_link_token", "in": "path", "description": "Public payment-link token from Dashboard", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to hosted checkout URL" }, "404": { "description": "Payment link not found or inactive" }, "default": { "description": "RFC 9457 Problem Details for an API failure not represented by a more specific protocol response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "ApplicationAuthProfile": { "type": "string", "description": "Coarse authentication posture selected per tenant application.", "enum": [ "relaxed", "normal", "strict", "critical" ] }, "CapabilitiesResponse": { "type": "object", "required": [ "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/CapabilityFlags" } } }, "CapabilityFlags": { "type": "object", "required": [ "sms_verification", "phone_authentication", "phone_recovery", "phone_two_factor", "passkeys", "two_factor_totp", "two_factor_passkeys", "magic_link", "email_verification", "password_reset", "social_login", "social_recovery", "agents", "api_keys", "billing", "commerce", "credential_vault", "delegations", "referrals", "scim", "wallets" ], "properties": { "agents": { "type": "boolean" }, "api_keys": { "type": "boolean" }, "billing": { "type": "boolean" }, "commerce": { "type": "boolean" }, "credential_vault": { "type": "boolean" }, "delegations": { "type": "boolean" }, "email_verification": { "type": "boolean" }, "magic_link": { "type": "boolean" }, "passkeys": { "type": "boolean" }, "password_reset": { "type": "boolean" }, "phone_authentication": { "type": "boolean" }, "phone_recovery": { "type": "boolean" }, "phone_two_factor": { "type": "boolean" }, "referrals": { "type": "boolean" }, "scim": { "type": "boolean" }, "sms_verification": { "type": "boolean" }, "social_login": { "type": "boolean" }, "social_recovery": { "type": "boolean" }, "two_factor_passkeys": { "type": "boolean" }, "two_factor_totp": { "type": "boolean" }, "wallets": { "type": "boolean" } } }, "ChallengeId": { "type": "string", "format": "uuid", "description": "Newtype for challenge identifiers (agent auth)." }, "ChallengeRequest": { "type": "object", "description": "Request to create a new challenge for signing.", "required": [ "key_fingerprint" ], "properties": { "key_fingerprint": { "$ref": "#/components/schemas/KeyFingerprint", "description": "Hex-encoded SHA-256 fingerprint of the agent's public key." }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeString", "description": "Requested OAuth scopes (space-separated)." } ] }, "tenant_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TenantId", "description": "Optional tenant UUID for shared-host routing; omission uses normal tenant resolution." } ] } } }, "ClientId": { "type": "string" }, "ClientReadResponse": { "type": "object", "description": "RFC 7592 – Client Read response (metadata without secret).", "required": [ "client_id", "redirect_uris", "auth_profile" ], "properties": { "allowed_origins": { "type": "array", "items": { "type": "string" } }, "auth_profile": { "$ref": "#/components/schemas/ApplicationAuthProfile", "description": "SigID extension: effective application authentication profile." }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "client_name": { "type": [ "string", "null" ] }, "client_uri": { "type": [ "string", "null" ] }, "contacts": { "type": [ "array", "null" ], "items": { "type": "string" } }, "grant_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/GrantType" } }, "initiate_login_uri": { "type": [ "string", "null" ] }, "jwks": { "description": "Inline JWKS (present for private_key_jwt clients)." }, "jwks_uri": { "type": [ "string", "null" ], "description": "Remote JWKS URI (present for private_key_jwt clients using remote keys)." }, "logo_uri": { "type": [ "string", "null" ] }, "policy_uri": { "type": [ "string", "null" ] }, "post_logout_redirect_uris": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RedirectUri" } }, "redirect_uris": { "type": "array", "items": { "$ref": "#/components/schemas/RedirectUri" } }, "response_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ResponseType" } }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeString" } ] }, "signup_optional_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/SharedProfileField" } }, "signup_required_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/SharedProfileField" } }, "software_id": { "type": [ "string", "null" ], "description": "Software identifier (RFC 7591 §2)." }, "software_version": { "type": [ "string", "null" ], "description": "Software version (RFC 7591 §2)." }, "token_endpoint_auth_method": { "type": [ "string", "null" ] }, "tos_uri": { "type": [ "string", "null" ] }, "web_origins": { "type": "array", "items": { "type": "string" } } } }, "ClientRegistrationRequest": { "type": "object", "description": "RFC 7591 §2 – Client Metadata for Dynamic Client Registration.", "required": [ "redirect_uris" ], "properties": { "allowed_origins": { "type": "array", "items": { "type": "string" }, "description": "SigID extension: exact browser origins allowed to call browser OAuth endpoints." }, "auth_profile": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApplicationAuthProfile", "description": "SigID extension: tenant application authentication profile." } ] }, "client_name": { "type": [ "string", "null" ] }, "client_uri": { "type": [ "string", "null" ] }, "contacts": { "type": [ "array", "null" ], "items": { "type": "string" } }, "grant_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/GrantType" } }, "initiate_login_uri": { "type": [ "string", "null" ], "description": "OIDC RP-initiated login route." }, "jwks": { "description": "Inline JWKS for private_key_jwt clients (RFC 7591 §2)." }, "jwks_uri": { "type": [ "string", "null" ], "description": "Remote JWKS URI alternative to inline `jwks` (RFC 7591 §2)." }, "logo_uri": { "type": [ "string", "null" ] }, "policy_uri": { "type": [ "string", "null" ] }, "post_logout_redirect_uris": { "type": [ "array", "null" ], "items": { "type": "string" } }, "redirect_uris": { "type": "array", "items": { "$ref": "#/components/schemas/RedirectUri" } }, "response_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ResponseType" } }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeString" } ] }, "signup_optional_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/SharedProfileField" }, "description": "Non-standard SigID extension: profile metadata fields requested on hosted signup." }, "signup_required_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/SharedProfileField" }, "description": "Non-standard SigID extension: profile metadata fields required on hosted signup." }, "software_id": { "type": [ "string", "null" ], "description": "Software identifier (RFC 7591 §2)." }, "software_statement": { "type": [ "string", "null" ], "description": "Software statement JWT (RFC 7591 §2.3)." }, "software_version": { "type": [ "string", "null" ], "description": "Software version (RFC 7591 §2)." }, "token_endpoint_auth_method": { "type": [ "string", "null" ] }, "tos_uri": { "type": [ "string", "null" ] }, "web_origins": { "type": "array", "items": { "type": "string" }, "description": "Browser origins allowed for front-channel web flows such as silent auth." } } }, "ClientRegistrationResponse": { "type": "object", "description": "RFC 7591 §3.2.1 – Client Information Response.", "required": [ "client_id", "registration_access_token", "registration_client_uri", "redirect_uris", "auth_profile" ], "properties": { "allowed_origins": { "type": "array", "items": { "type": "string" } }, "auth_profile": { "$ref": "#/components/schemas/ApplicationAuthProfile", "description": "SigID extension: effective application authentication profile." }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "client_id_issued_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix timestamp when client_id was issued (RFC 7591 §3.2.1)." }, "client_name": { "type": [ "string", "null" ] }, "client_secret": { "type": [ "string", "null" ] }, "client_secret_expires_at": { "type": [ "integer", "null" ], "format": "int64" }, "client_uri": { "type": [ "string", "null" ] }, "contacts": { "type": [ "array", "null" ], "items": { "type": "string" } }, "grant_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/GrantType" } }, "initiate_login_uri": { "type": [ "string", "null" ] }, "jwks": { "description": "Inline JWKS (present for private_key_jwt clients)." }, "jwks_uri": { "type": [ "string", "null" ], "description": "Remote JWKS URI (present for private_key_jwt clients using remote keys)." }, "logo_uri": { "type": [ "string", "null" ] }, "policy_uri": { "type": [ "string", "null" ] }, "post_logout_redirect_uris": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RedirectUri" } }, "redirect_uris": { "type": "array", "items": { "$ref": "#/components/schemas/RedirectUri" } }, "registration_access_token": { "type": "string" }, "registration_client_uri": { "type": "string" }, "response_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ResponseType" } }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeString" } ] }, "signup_optional_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/SharedProfileField" } }, "signup_required_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/SharedProfileField" } }, "software_id": { "type": [ "string", "null" ], "description": "Software identifier (RFC 7591 §2)." }, "software_statement": { "type": [ "string", "null" ], "description": "Software statement JWT (echoed back if provided during registration)." }, "software_version": { "type": [ "string", "null" ], "description": "Software version (RFC 7591 §2)." }, "token_endpoint_auth_method": { "type": [ "string", "null" ] }, "tos_uri": { "type": [ "string", "null" ] }, "web_origins": { "type": "array", "items": { "type": "string" } } } }, "CnfClaim": { "type": "object", "description": "RFC 7800 confirmation claim for sender-constrained tokens.", "required": [ "jkt" ], "properties": { "jkt": { "$ref": "#/components/schemas/Jkt", "description": "JWK SHA-256 Thumbprint (RFC 7638)." } } }, "CodeVerifier": { "type": "string", "description": "PKCE code verifier (43-128 unreserved characters per RFC 7636)." }, "CommerceBuyerId": { "type": "string", "format": "uuid", "description": "Newtype for commerce buyer identifiers." }, "CommerceBuyerType": { "type": "string", "enum": [ "unknown", "consumer", "business" ] }, "CommerceChargeId": { "type": "string", "format": "uuid", "description": "Newtype for commerce-charge identifiers." }, "CommerceChargeStatus": { "type": "string", "enum": [ "pending", "requires_action", "succeeded", "failed", "partially_refunded", "refunded" ] }, "CommerceFulfillmentView": { "type": "object", "description": "Public fulfillment view of a charge: everything a third-party integrator\nneeds to reconcile a `commerce.payment.*` webhook without the merchant\nadmin API. `metadata` carries the correlation key the merchant set at\ncheckout (e.g. their internal user/product ids). See ADR 0013.", "required": [ "charge_id", "status", "currency", "gross_amount_minor", "refunded_amount_minor", "metadata", "created_at" ], "properties": { "buyer_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommerceBuyerId" } ] }, "charge_id": { "$ref": "#/components/schemas/CommerceChargeId" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "customer_email": { "type": [ "string", "null" ] }, "gross_amount_minor": { "type": "integer", "format": "int64", "description": "Gross amount settled, minor units." }, "metadata": { "description": "Merchant-defined JSON set on the payment link / checkout session." }, "price_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommercePriceId" } ] }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommerceProductId" } ] }, "refunded_amount_minor": { "type": "integer", "format": "int64", "description": "Cumulative refunded amount, minor units." }, "status": { "$ref": "#/components/schemas/CommerceChargeStatus" } } }, "CommercePriceId": { "type": "string", "format": "uuid", "description": "Newtype for commerce-price identifiers." }, "CommerceProductId": { "type": "string", "format": "uuid", "description": "Newtype for commerce-product identifiers." }, "CompletePresentationRequest": { "type": "object", "required": [ "hosted_auth_transaction_id", "state", "browser_binding" ], "properties": { "browser_binding": { "type": "string" }, "hosted_auth_transaction_id": { "type": "string", "format": "uuid" }, "state": { "type": "string" } } }, "CompletePresentationResponse": { "type": "object", "required": [ "redirect_uri" ], "properties": { "redirect_uri": { "type": "string" } } }, "CreateCheckoutSessionRequest": { "type": "object", "required": [ "price_id", "success_url", "cancel_url", "idempotency_key" ], "properties": { "buyer_country": { "type": [ "string", "null" ] }, "buyer_region": { "type": [ "string", "null" ] }, "buyer_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommerceBuyerType" } ] }, "cancel_url": { "type": "string" }, "customer_email": { "type": [ "string", "null" ] }, "idempotency_key": { "type": "string" }, "metadata": { "type": "object" }, "price_id": { "$ref": "#/components/schemas/CommercePriceId" }, "success_url": { "type": "string" }, "tenant_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CreateCredentialOfferRequest": { "type": "object", "required": [ "credential_configuration_id" ], "properties": { "credential_configuration_id": { "$ref": "#/components/schemas/CredentialConfigurationId" } } }, "CreatePresentationRequest": { "type": "object", "required": [ "hosted_auth_transaction_id", "dcql_template", "browser_binding" ], "properties": { "browser_binding": { "type": "string" }, "dcql_template": { "$ref": "#/components/schemas/DcqlTemplateId" }, "hosted_auth_transaction_id": { "type": "string", "format": "uuid" } } }, "CreateSubscriptionCheckoutSessionRequest": { "type": "object", "required": [ "price_id", "success_url", "cancel_url", "customer_email", "idempotency_key" ], "properties": { "buyer_country": { "type": [ "string", "null" ] }, "buyer_region": { "type": [ "string", "null" ] }, "buyer_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommerceBuyerType" } ] }, "cancel_url": { "type": "string" }, "customer_email": { "type": "string" }, "idempotency_key": { "type": "string" }, "metadata": { "type": "object" }, "price_id": { "$ref": "#/components/schemas/CommercePriceId" }, "success_url": { "type": "string" }, "tenant_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CredentialConfiguration": { "type": "object", "required": [ "format", "scope", "vct", "cryptographic_binding_methods_supported", "credential_signing_alg_values_supported", "proof_types_supported", "display" ], "properties": { "credential_signing_alg_values_supported": { "type": "array", "items": { "type": "string" } }, "cryptographic_binding_methods_supported": { "type": "array", "items": { "type": "string" } }, "display": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialDisplay" } }, "format": { "type": "string" }, "proof_types_supported": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ProofTypeMetadata" }, "propertyNames": { "type": "string" } }, "scope": { "type": "string" }, "vct": { "type": "string" } } }, "CredentialConfigurationId": { "type": "string", "enum": [ "SigIDHumanCredential", "SigIDAgentCredential", "SigIDOrganizationMembershipCredential" ] }, "CredentialDisplay": { "type": "object", "required": [ "name", "locale" ], "properties": { "locale": { "type": "string" }, "name": { "type": "string" } } }, "CredentialIssuerMetadata": { "type": "object", "required": [ "credential_issuer", "authorization_servers", "credential_endpoint", "nonce_endpoint", "credential_configurations_supported", "display" ], "properties": { "authorization_servers": { "type": "array", "items": { "type": "string" } }, "credential_configurations_supported": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CredentialConfiguration" }, "propertyNames": { "type": "string" } }, "credential_endpoint": { "type": "string" }, "credential_issuer": { "type": "string" }, "display": { "type": "array", "items": { "$ref": "#/components/schemas/IssuerDisplay" } }, "nonce_endpoint": { "type": "string" } } }, "CredentialOfferCreated": { "type": "object", "required": [ "credential_offer_uri", "expires_in" ], "properties": { "credential_offer_uri": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64", "minimum": 0 }, "qr_code_svg": { "type": [ "string", "null" ], "description": "Server-rendered QR code for `credential_offer_uri`. The transaction\ncode is deliberately excluded from this payload." }, "transaction_code": { "type": [ "string", "null" ], "description": "Separately deliver this code to the holder. It is never embedded in the\nQR/deep-link payload." } } }, "CredentialProofs": { "type": "object", "required": [ "jwt" ], "properties": { "jwt": { "type": "array", "items": { "type": "string" } } } }, "CredentialRequest": { "type": "object", "required": [ "credential_configuration_id", "proofs" ], "properties": { "credential_configuration_id": { "$ref": "#/components/schemas/CredentialConfigurationId" }, "proofs": { "$ref": "#/components/schemas/CredentialProofs" } } }, "CredentialResponse": { "type": "object", "required": [ "credentials" ], "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/IssuedCredential" } } } }, "DcqlTemplateId": { "type": "string", "enum": [ "human", "agent", "organization_membership", "mobile_driving_licence" ] }, "DirectPostAccepted": { "type": "object", "required": [ "status", "redirect_uri" ], "properties": { "redirect_uri": { "type": "string" }, "status": { "type": "string" } } }, "DirectPostForm": { "type": "object", "required": [ "state" ], "properties": { "error": { "type": [ "string", "null" ], "description": "OID4VP authorization error returned when the holder cancels or the\nwallet cannot satisfy the request." }, "error_description": { "type": [ "string", "null" ] }, "error_uri": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "vp_token": { "type": [ "string", "null" ], "description": "JSON-encoded OID4VP `vp_token` form parameter keyed by DCQL query ID." } } }, "GrantType": { "type": "string", "description": "OAuth 2.0 grant types supported by SigID.", "enum": [ "authorization_code", "client_credentials", "urn:ietf:params:oauth:grant-type:device_code", "refresh_token", "urn:openid:params:grant-type:ciba", "urn:ietf:params:oauth:grant-type:token-exchange", "urn:ietf:params:oauth:grant-type:pre-authorized_code" ] }, "IntrospectionRequest": { "type": "object", "description": "Introspection request (RFC 7662).", "required": [ "token" ], "properties": { "client_assertion": { "type": [ "string", "null" ] }, "client_assertion_type": { "type": [ "string", "null" ] }, "client_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ClientId" } ] }, "client_secret": { "type": [ "string", "null" ] }, "token": { "type": "string" }, "token_type_hint": { "type": [ "string", "null" ] } } }, "IntrospectionResponse": { "type": "object", "description": "Token introspection response (RFC 7662).", "required": [ "active" ], "properties": { "active": { "type": "boolean" }, "aud": { "type": [ "string", "null" ] }, "client_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ClientId" } ] }, "cnf": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CnfClaim", "description": "RFC 7800 confirmation claim (present for DPoP-bound tokens)." } ] }, "exp": { "type": [ "integer", "null" ], "format": "int64" }, "iat": { "type": [ "integer", "null" ], "format": "int64" }, "iss": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IssuerUrl" } ] }, "jti": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Jti" } ] }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeString" } ] }, "sub": { "type": [ "string", "null" ] }, "token_type": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } } }, "IssuedCredential": { "type": "object", "required": [ "credential" ], "properties": { "credential": { "type": "string" } } }, "IssuerDisplay": { "type": "object", "required": [ "name", "locale" ], "properties": { "locale": { "type": "string" }, "name": { "type": "string" } } }, "IssuerUrl": { "type": "string" }, "Jkt": { "type": "string", "description": "JWK SHA-256 Thumbprint (RFC 7638) for DPoP binding." }, "Jti": { "type": "string", "description": "JWT Token ID (`jti` claim)." }, "KeyAlgorithm": { "type": "string", "enum": [ "ed25519", "es256", "es256k", "bip340" ] }, "KeyFingerprint": { "type": "string", "description": "Hex-encoded SHA-256 fingerprint of a public key." }, "NonceResponse": { "type": "object", "required": [ "c_nonce" ], "properties": { "c_nonce": { "type": "string" } } }, "OidcDiscovery": { "type": "object", "description": "OIDC discovery document (OpenID Connect Discovery 1.0 + RFC 8414).\nOmits `registration_endpoint` unless `oidc.allow_dynamic_registration`.\n`end_session_endpoint` is always present.", "required": [ "issuer", "authorization_endpoint", "token_endpoint", "jwks_uri", "userinfo_endpoint", "scopes_supported", "response_types_supported", "response_modes_supported", "grant_types_supported", "token_endpoint_auth_methods_supported", "code_challenge_methods_supported", "subject_types_supported", "id_token_signing_alg_values_supported", "claims_supported" ], "properties": { "acr_values_supported": { "type": [ "array", "null" ], "items": { "type": "string" } }, "authorization_details_types_supported": { "type": [ "array", "null" ], "items": { "type": "string" } }, "authorization_endpoint": { "type": "string" }, "backchannel_authentication_endpoint": { "type": [ "string", "null" ], "description": "OIDC CIBA backchannel authentication endpoint." }, "backchannel_token_delivery_modes_supported": { "type": [ "array", "null" ], "items": { "type": "string" } }, "backchannel_user_code_parameter_supported": { "type": [ "boolean", "null" ] }, "claims_parameter_supported": { "type": [ "boolean", "null" ] }, "claims_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "device_authorization_endpoint": { "type": [ "string", "null" ], "description": "RFC 8628 Device Authorization Endpoint." }, "dpop_signing_alg_values_supported": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "RFC 9449: DPoP signing algorithms supported by the server." }, "end_session_endpoint": { "type": [ "string", "null" ], "description": "OIDC RP-Initiated Logout 1.0. Always present." }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "id_token_signing_alg_values_supported": { "type": "array", "items": { "type": "string" } }, "introspection_endpoint": { "type": [ "string", "null" ] }, "issuer": { "$ref": "#/components/schemas/IssuerUrl" }, "jwks_uri": { "type": "string" }, "pre_authorized_grant_anonymous_access_supported": { "type": [ "boolean", "null" ], "description": "OID4VCI: token requests using the pre-authorized grant do not require\na client identifier or client authentication." }, "prompt_values_supported": { "type": [ "array", "null" ], "items": { "type": "string" } }, "pushed_authorization_request_endpoint": { "type": [ "string", "null" ], "description": "RFC 9126 Pushed Authorization Request endpoint." }, "registration_endpoint": { "type": [ "string", "null" ], "description": "RFC 7591 Dynamic Client Registration. Only present when enabled." }, "request_uri_parameter_supported": { "type": [ "boolean", "null" ] }, "require_pushed_authorization_requests": { "type": [ "boolean", "null" ] }, "response_modes_supported": { "type": "array", "items": { "type": "string" } }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "revocation_endpoint": { "type": [ "string", "null" ] }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "subject_types_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint": { "type": "string" }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_signing_alg_values_supported": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Signing algorithms supported for private_key_jwt client assertions." }, "userinfo_endpoint": { "type": "string" } } }, "PaymentLinkCheckoutRequest": { "type": "object", "required": [ "idempotency_key" ], "properties": { "buyer_country": { "type": [ "string", "null" ] }, "buyer_region": { "type": [ "string", "null" ] }, "buyer_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommerceBuyerType" } ] }, "customer_email": { "type": [ "string", "null" ] }, "idempotency_key": { "type": "string" }, "metadata": { "type": "object" } } }, "PresentationRequestCreated": { "type": "object", "required": [ "state", "wallet_authorization_uri", "expires_in" ], "properties": { "expires_in": { "type": "integer", "format": "int64", "minimum": 0 }, "state": { "type": "string" }, "wallet_authorization_uri": { "type": "string" } } }, "ProblemDetails": { "type": "object", "description": "Default SigID API error envelope.\n\nOAuth, OIDC, OpenID4VC, and SCIM operations retain their protocol-specific\nerror shapes. Ordinary API failures use RFC 9457 Problem Details.", "required": [ "type", "title", "status", "detail" ], "properties": { "detail": { "type": "string", "description": "Safe, human-readable explanation of this occurrence." }, "resolution": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Concrete recovery actions when the server can provide them safely." }, "retry_after": { "type": [ "integer", "null" ], "format": "int64", "description": "Seconds to wait before retrying a throttled operation.", "minimum": 0 }, "status": { "type": "integer", "format": "int32", "description": "HTTP status code repeated in the body.", "minimum": 0 }, "title": { "type": "string", "description": "Short, status-level summary." }, "type": { "type": "string", "description": "Stable URI identifying the problem class." } } }, "ProofTypeMetadata": { "type": "object", "required": [ "proof_signing_alg_values_supported" ], "properties": { "proof_signing_alg_values_supported": { "type": "array", "items": { "type": "string" } } } }, "ProtocolErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": [ "string", "null" ] } } }, "PushedAuthorizationResponse": { "type": "object", "description": "Pushed Authorization Request response (RFC 9126 §2.2).", "required": [ "request_uri", "expires_in" ], "properties": { "expires_in": { "type": "integer", "format": "int64", "minimum": 0 }, "request_uri": { "type": "string" } } }, "RedirectUri": { "type": "string" }, "ResponseType": { "type": "string", "description": "OAuth 2.0 response types.", "enum": [ "code" ] }, "RevocationRequest": { "type": "object", "description": "Revocation request (RFC 7009).", "required": [ "token" ], "properties": { "client_assertion": { "type": [ "string", "null" ] }, "client_assertion_type": { "type": [ "string", "null" ] }, "client_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ClientId" } ] }, "client_secret": { "type": [ "string", "null" ] }, "token": { "type": "string" }, "token_type_hint": { "type": [ "string", "null" ] } } }, "ScopeString": { "type": "string", "description": "Space-separated OAuth 2.0 scope string." }, "SdJwtVcIssuerMetadata": { "type": "object", "required": [ "issuer", "jwks_uri" ], "properties": { "issuer": { "type": "string" }, "jwks_uri": { "type": "string" } } }, "SharedProfileField": { "type": "string", "description": "Field-level profile sharing consent for tenant-visible PII projection.\n\nEach variant names a discrete field that the user may choose to share\nwith a tenant through `tenant_membership.shared_profile_fields`.", "enum": [ "name", "avatar", "email", "phone" ] }, "TenantId": { "type": "string", "format": "uuid", "description": "Newtype for tenant identifiers." }, "TokenRequest": { "type": "object", "description": "Token request parameters (POST /oauth/token).", "required": [ "grant_type" ], "properties": { "actor_token": { "type": [ "string", "null" ] }, "actor_token_type": { "type": [ "string", "null" ] }, "auth_req_id": { "type": [ "string", "null" ], "description": "OIDC CIBA token polling parameter." }, "client_assertion": { "type": [ "string", "null" ], "description": "RFC 7523 private_key_jwt client assertion." }, "client_assertion_type": { "type": [ "string", "null" ] }, "client_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ClientId" } ] }, "client_secret": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "code_verifier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CodeVerifier" } ] }, "device_code": { "type": [ "string", "null" ], "description": "RFC 8628 §3.4 device code polling parameter." }, "grant_type": { "$ref": "#/components/schemas/GrantType" }, "pre-authorized_code": { "type": [ "string", "null" ], "description": "OpenID4VCI pre-authorized code and separately delivered transaction code." }, "redirect_uri": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RedirectUri" } ] }, "refresh_token": { "type": [ "string", "null" ] }, "requested_token_type": { "type": [ "string", "null" ], "description": "RFC 8693 §2.1: requested token type (e.g. external-provider exchange)." }, "resource": { "type": [ "string", "null" ], "description": "RFC 8693 §2.1: target resource (e.g. provider name like \"google\")." }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeString" } ] }, "subject_token": { "type": [ "string", "null" ], "description": "Token exchange fields (RFC 8693)." }, "subject_token_type": { "type": [ "string", "null" ] }, "tenant_id": { "type": [ "string", "null" ], "description": "Shared-host tenant routing reference. Accepts a tenant UUID or canonical slug." }, "tx_code": { "type": [ "string", "null" ] } } }, "TokenResponse": { "type": "object", "description": "Token response (RFC 6749 §5.1).", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string" }, "authorization_details": { "description": "RFC 9396 authorization details granted for this token." }, "expires_in": { "type": "integer", "format": "int64", "minimum": 0 }, "id_token": { "type": [ "string", "null" ] }, "issued_token_type": { "type": [ "string", "null" ], "description": "RFC 8693 §2.2.1: issued token type (present for token exchange responses)." }, "refresh_token": { "type": [ "string", "null" ] }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeString" } ] }, "token_type": { "type": "string" } } }, "VerifyRequest": { "type": "object", "description": "Request to verify a signed challenge.", "required": [ "challenge_id", "signature", "algorithm" ], "properties": { "algorithm": { "$ref": "#/components/schemas/KeyAlgorithm", "description": "The signature algorithm used." }, "challenge_id": { "$ref": "#/components/schemas/ChallengeId", "description": "The challenge ID from the challenge response." }, "signature": { "type": "string", "description": "Base64-encoded signature." } } }, "WorkspaceBootstrapMetadata": { "type": "object", "description": "Public key-proof binding for cold workspace provisioning. A tenant slug is\na routing selector; signatures must bind the resolved UUID and issuer.", "required": [ "issuer", "tenant_id", "tenant_slug" ], "properties": { "issuer": { "type": "string" }, "tenant_id": { "$ref": "#/components/schemas/TenantId" }, "tenant_slug": { "type": "string" } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "bearer_auth": { "type": "http", "scheme": "bearer" }, "dpop_auth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "DPoP-bound access token using `DPoP `." }, "dpop_proof": { "type": "apiKey", "in": "header", "name": "DPoP", "description": "RFC 9449 proof JWT bound to this request and access token." }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.sigid.org/oauth/authorize", "tokenUrl": "https://auth.sigid.org/oauth/token", "scopes": { "email": "Read the subject's email claims when consent and policy allow.", "offline_access": "Request a refresh token for access while the subject is absent.", "openid": "Authenticate the subject and return an OpenID Connect ID token.", "phone": "Read the subject's phone claims when consent and policy allow.", "profile": "Read the subject's standard profile claims." } }, "clientCredentials": { "tokenUrl": "https://auth.sigid.org/oauth/token", "scopes": { "email": "Read the subject's email claims when consent and policy allow.", "offline_access": "Request a refresh token for access while the subject is absent.", "openid": "Authenticate the subject and return an OpenID Connect ID token.", "phone": "Read the subject's phone claims when consent and policy allow.", "profile": "Read the subject's standard profile claims." } } }, "description": "OAuth 2.1 access through the canonical SigID issuer. Request only the scopes required for the current operation; tenant policy and consent may narrow the grant." }, "session_cookie": { "type": "apiKey", "in": "cookie", "name": "sigid_session" } } }, "tags": [ { "name": "OAuth", "description": "OAuth 2.0 / OIDC protocol endpoints" }, { "name": "Well-Known", "description": "OIDC discovery and JWKS endpoints" }, { "name": "OpenID4VC", "description": "OpenID4VC issuance and presentation endpoints" }, { "name": "Health", "description": "Health and readiness probes" }, { "name": "Capabilities", "description": "Public feature capability discovery" }, { "name": "Agent", "description": "Agent authentication challenges" }, { "name": "Commerce", "description": "Public buyer commerce: payment links, checkout, x402" } ] }