{ "openapi": "3.1.0", "info": { "title": "Clams Auth API", "description": "Authentication and token endpoints for Clams.\n\nSee `authentication.md` in the same docs site for an end-to-end walkthrough (browser login session -> token exchange -> refresh).", "license": { "name": "" }, "version": "1.0.2" }, "servers": [ { "url": "https://auth.clams.tech", "description": "Production" } ], "paths": { "/.well-known/jwks.json": { "get": { "tags": [ "Discovery" ], "operationId": "jwks_docs", "responses": { "200": { "description": "JWKS document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiJwksSet" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/.well-known/openid-configuration": { "get": { "tags": [ "Discovery" ], "operationId": "discovery_docs", "responses": { "200": { "description": "OIDC discovery document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryDocument" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/account/notices/{notice_id}/receipts": { "post": { "tags": [ "Account" ], "operationId": "record_account_notice_receipt_docs", "parameters": [ { "name": "notice_id", "in": "path", "description": "Stable account-notice id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountNoticeReceiptRequest" } } }, "required": true }, "responses": { "204": { "description": "Receipt recorded" }, "400": { "description": "Invalid request or unknown notice id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/auth/logout": { "post": { "tags": [ "Account" ], "operationId": "logout_docs", "responses": { "204": { "description": "Logged out" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/auth/logout/all": { "post": { "tags": [ "Account" ], "operationId": "logout_all_docs", "responses": { "204": { "description": "Logged out everywhere" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/auth/whoami": { "get": { "tags": [ "Account" ], "operationId": "whoami_docs", "responses": { "200": { "description": "Authenticated subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoamiResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/cancel": { "get": { "tags": [ "Billing" ], "operationId": "billing_cancel_docs", "responses": { "200": { "description": "Browser payment-cancel page" } } } }, "/v1/billing/checkout/{checkout_token}": { "get": { "tags": [ "Billing" ], "operationId": "phoenixd_checkout_page_docs", "parameters": [ { "name": "checkout_token", "in": "path", "description": "Opaque Phoenixd checkout token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authd-hosted Phoenixd Lightning checkout page" }, "400": { "description": "Invalid or unknown checkout token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Provider or quote service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/billing/checkout/{checkout_token}/status": { "get": { "tags": [ "Billing" ], "operationId": "phoenixd_checkout_status_docs", "parameters": [ { "name": "checkout_token", "in": "path", "description": "Opaque Phoenixd checkout token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Phoenixd Lightning checkout status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiPhoenixdCheckoutStatusResponse" } } } }, "400": { "description": "Invalid or unknown checkout token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Provider or quote service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/billing/existing-root-migrations": { "post": { "tags": [ "Billing" ], "operationId": "begin_existing_root_migration_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBeginExistingRootMigrationRequest" } } }, "required": true }, "responses": { "201": { "description": "Existing-root migration challenge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiInstanceBindingChallengeResponse" } } } }, "400": { "description": "Invalid migration evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Migration policy or proof eligibility denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/existing-root-migrations/complete": { "post": { "tags": [ "Billing" ], "operationId": "complete_existing_root_migration_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCompleteExistingRootMigrationRequest" } } }, "required": true }, "responses": { "200": { "description": "Existing-root migration completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiExistingRootMigrationResponse" } } } }, "400": { "description": "Invalid or expired migration proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Migration policy denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/instance-binding-challenges": { "post": { "tags": [ "Billing" ], "operationId": "create_instance_binding_challenge_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateInstanceBindingChallengeRequest" } } }, "required": true }, "responses": { "201": { "description": "Instance binding challenge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiInstanceBindingChallengeResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Subject is not authorized for the instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/instances/{instance_id}/owner": { "get": { "tags": [ "Billing" ], "operationId": "billing_instance_owner_docs", "parameters": [ { "name": "instance_id", "in": "path", "description": "Backend instance id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Billing owner status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBillingInstanceOwnerResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Subject is not the active billing owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/instances/{instance_id}/owner/transfer": { "post": { "tags": [ "Billing" ], "operationId": "transfer_billing_instance_owner_docs", "parameters": [ { "name": "instance_id", "in": "path", "description": "Backend instance id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiTransferBillingInstanceOwnerRequest" } } }, "required": true }, "responses": { "200": { "description": "Billing owner transferred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiTransferBillingInstanceOwnerResponse" } } } }, "400": { "description": "Invalid request or proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Subject is not the active billing owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/invoices": { "post": { "tags": [ "Billing" ], "operationId": "create_billing_invoice_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateBillingInvoiceRequest" } } }, "required": true }, "responses": { "201": { "description": "Hosted payment invoice created or reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBillingInvoiceResponse" } } } }, "400": { "description": "Invalid request or verified email required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "409": { "description": "Checkout policy is stale or an identical checkout is still pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateInvoiceConflictResponse" } } } }, "503": { "description": "Provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/invoices/{invoice_id}": { "get": { "tags": [ "Billing" ], "operationId": "get_billing_invoice_docs", "parameters": [ { "name": "invoice_id", "in": "path", "description": "Internal billing invoice id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBillingInvoiceResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/legal": { "get": { "tags": [ "Billing" ], "operationId": "billing_legal_docs", "responses": { "200": { "description": "Current checkout legal facts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBillingLegalResponse" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "500": { "description": "Authentication or server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Strict legal manifest resolution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/license": { "get": { "tags": [ "Billing" ], "operationId": "billing_license_docs", "responses": { "200": { "description": "Current license state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBillingLicenseResponse" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/offers": { "get": { "tags": [ "Billing" ], "operationId": "billing_offers_docs", "responses": { "200": { "description": "Public billing offers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBillingOffersResponse" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/profile-capacity/quote": { "post": { "tags": [ "Billing" ], "operationId": "quote_profile_capacity_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiQuoteProfileCapacityRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile-capacity checkout quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProfileCapacityQuoteResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Subject is not authorized for the instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/profile-capacity/reservations": { "post": { "tags": [ "Billing" ], "operationId": "create_profile_capacity_reservation_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateProfileCapacityReservationRequest" } } }, "required": true }, "responses": { "201": { "description": "Profile-capacity reservation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProfileCapacityReservationResponse" } } } }, "400": { "description": "Invalid request or no available capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Subject is not authorized for the instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/profile-capacity/reservations/{reservation_id}/commit": { "post": { "tags": [ "Billing" ], "operationId": "commit_profile_capacity_reservation_docs", "parameters": [ { "name": "reservation_id", "in": "path", "description": "Profile-capacity reservation id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiUpdateProfileCapacityReservationRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile-capacity reservation committed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProfileCapacityReservationResponse" } } } }, "400": { "description": "Invalid request or transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Subject is not authorized for the instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/profile-capacity/reservations/{reservation_id}/release": { "post": { "tags": [ "Billing" ], "operationId": "release_profile_capacity_reservation_docs", "parameters": [ { "name": "reservation_id", "in": "path", "description": "Profile-capacity reservation id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiUpdateProfileCapacityReservationRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile-capacity reservation released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProfileCapacityReservationResponse" } } } }, "400": { "description": "Invalid request or transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "403": { "description": "Subject is not authorized for the instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/profile-capacity/revisions/validate": { "post": { "tags": [ "Billing" ], "operationId": "validate_profile_capacity_revision_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiValidateProfileCapacityRevisionRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile-capacity revision validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiValidateProfileCapacityRevisionResponse" } } } }, "400": { "description": "Invalid request or unusable token claim", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "503": { "description": "Instance binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/return": { "get": { "tags": [ "Billing" ], "operationId": "billing_return_docs", "responses": { "200": { "description": "Browser payment-return page" } } } }, "/v1/billing/webhooks/phoenixd": { "post": { "tags": [ "Billing" ], "operationId": "phoenixd_billing_webhook_docs", "responses": { "200": { "description": "Phoenixd webhook accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBillingWebhookResponse" } } } }, "400": { "description": "Invalid signature or payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/billing/webhooks/stripe": { "post": { "tags": [ "Billing" ], "operationId": "stripe_billing_webhook_docs", "responses": { "200": { "description": "Stripe webhook accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiBillingWebhookResponse" } } } }, "400": { "description": "Invalid signature or payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/connections/oauth/credentials/access-token": { "post": { "tags": [ "Connection OAuth" ], "operationId": "connection_oauth_access_token_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiConnectionOAuthAccessTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Short-lived provider access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiConnectionOAuthAccessTokenResponse" } } } }, "400": { "description": "Invalid request or unsupported OAuth provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/connections/oauth/credentials/{credential_ref}/disconnect": { "post": { "tags": [ "Connection OAuth" ], "operationId": "connection_oauth_disconnect_docs", "parameters": [ { "name": "credential_ref", "in": "path", "description": "Opaque hosted credential reference", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Hosted credential disconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiConnectionOAuthCredentialStatusResponse" } } } }, "400": { "description": "Invalid request or unsupported OAuth provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/connections/oauth/credentials/{credential_ref}/status": { "get": { "tags": [ "Connection OAuth" ], "operationId": "connection_oauth_status_docs", "parameters": [ { "name": "credential_ref", "in": "path", "description": "Opaque hosted credential reference", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Non-secret hosted credential status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiConnectionOAuthCredentialStatusResponse" } } } }, "400": { "description": "Invalid request or unsupported OAuth provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/connections/oauth/{provider_key}/callback": { "get": { "tags": [ "Connection OAuth" ], "operationId": "connection_oauth_callback_docs", "parameters": [ { "name": "provider_key", "in": "path", "description": "Connection OAuth provider key", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Provider callback state", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "Provider authorization code; required when error is absent", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "description": "Provider authorization error code; required when code is absent", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "description": "Provider authorization error description", "required": false, "schema": { "type": "string" } }, { "name": "error_uri", "in": "query", "description": "Provider authorization error reference URI", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Hosted provider callback accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiConnectionOAuthCredentialStatusResponse" } } } }, "400": { "description": "Invalid request or unsupported OAuth provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/connections/oauth/{provider_key}/start": { "post": { "tags": [ "Connection OAuth" ], "operationId": "connection_oauth_start_docs", "parameters": [ { "name": "provider_key", "in": "path", "description": "Connection OAuth provider key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiConnectionOAuthStartRequest" } } }, "required": true }, "responses": { "200": { "description": "Hosted provider authorization started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiConnectionOAuthStartResponse" } } } }, "400": { "description": "Invalid request or unsupported OAuth provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/oauth-clients": { "post": { "tags": [ "OAuth Clients" ], "operationId": "create_oauth_client_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateOAuthClientRequest" } } }, "required": true }, "responses": { "201": { "description": "OAuth client created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateOAuthClientResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/token": { "post": { "tags": [ "Tokens" ], "operationId": "token_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Tokens issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Auth failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/token/exchange": { "post": { "tags": [ "Tokens" ], "operationId": "token_exchange_docs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Tokens issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshGrantResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Subject token invalid/expired/revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/web/login/session/start": { "post": { "tags": [ "Login" ], "operationId": "login_session_start_docs", "parameters": [ { "name": "x-clams-login-session-protocol", "in": "header", "description": "Login session protocol; current clients send 2", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginSessionStartRequest" } } }, "required": true }, "responses": { "200": { "description": "Login session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginSessionStartResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "426": { "description": "Legacy login protocol disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } }, "/v1/web/login/session/{login_session_id}": { "get": { "tags": [ "Login" ], "operationId": "login_session_status_docs", "parameters": [ { "name": "login_session_id", "in": "path", "description": "Login session id (UUID v7)", "required": true, "schema": { "type": "string" } }, { "name": "x-clams-login-session-poll-secret", "in": "header", "description": "Client-held polling proof returned by session start", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Login session status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginSessionStatusResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "401": { "description": "Invalid polling proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } }, "426": { "description": "Legacy login protocol disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiErrorEnvelope" } } } } } } } }, "components": { "schemas": { "AccountNoticeId": { "type": "string", "description": "Stable account notice identifier.", "enum": [ "beta_2026_remaining_year_grant_v1" ] }, "AccountNoticeReceiptEvent": { "type": "string", "description": "Receipt event submitted by a notice-capable client.", "enum": [ "displayed", "acknowledged" ] }, "AccountNoticeReceiptRequest": { "type": "object", "description": "Request body for recording an account-notice receipt.", "required": [ "surface", "event" ], "properties": { "event": { "$ref": "#/components/schemas/AccountNoticeReceiptEvent", "description": "Receipt event being recorded." }, "surface": { "$ref": "#/components/schemas/AccountNoticeSurface", "description": "Surface that displayed or acknowledged the notice." } } }, "AccountNoticeResponse": { "type": "object", "description": "Notice payload returned to authenticated clients.", "required": [ "notice_id", "surface", "title", "body", "expires_at_epoch" ], "properties": { "body": { "type": "string", "description": "Human-readable notice body." }, "expires_at_epoch": { "type": "integer", "format": "int64", "description": "Epoch seconds after which clients should not display the notice.", "minimum": 0 }, "notice_id": { "$ref": "#/components/schemas/AccountNoticeId", "description": "Stable notice id used for receipts." }, "surface": { "$ref": "#/components/schemas/AccountNoticeSurface", "description": "Surface this response is intended for." }, "title": { "type": "string", "description": "Human-readable notice title." } } }, "AccountNoticeSurface": { "type": "string", "description": "Authenticated surface where an account notice can be displayed.", "enum": [ "login_success", "cli" ] }, "ClientCredentialsGrantResponse": { "type": "object", "description": "Response payload for client credentials grant requests.", "required": [ "access_token", "token_type", "expires_in", "audience" ], "properties": { "access_token": { "type": "string", "example": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJmZWVkYmFjayIsImV4cCI6MTcwMDAwMDAwMCwiaWF0IjoxNzAwMDAwMDAwLCJzZXNzaW9uX2lkIjoiMDE4OTBiOGMtNWNmZC03ZDVmLThmOTAtM2M3ZjRmNjJkODAxIiwic3ViIjoiODYyZmQ1ZWQtYWM5YS01YmZlLTk2ZjItYWIxZjUwMWEyYzk5IiwidXNlcl9pZCI6ImNsaWVudDpjbGlfMTIzIn0.signature" }, "audience": { "$ref": "#/components/schemas/RefreshGrantAudience" }, "expires_in": { "type": "integer", "format": "int64", "example": 300, "minimum": 1 }, "token_type": { "type": "string", "example": "bearer" } } }, "CodeChallengeMethod": { "type": "string", "description": "@impl(R-012) @s(S-012)\nEnum describing supported PKCE code challenge methods.", "enum": [ "S256" ] }, "DiscoveryDocument": { "type": "object", "description": "@impl(R-012) @s(S-012)\nSerializable OIDC discovery document that mirrors the HTTP response body.", "required": [ "issuer", "jwks_uri", "authorization_endpoint", "token_endpoint", "device_authorization_endpoint", "code_challenge_methods_supported", "grant_types_supported" ], "properties": { "authorization_endpoint": { "type": "string", "format": "uri", "example": "https://auth.clams.tech/v1/web/pkce/start" }, "code_challenge_methods_supported": { "type": "array", "items": { "$ref": "#/components/schemas/CodeChallengeMethod" } }, "device_authorization_endpoint": { "type": "string", "format": "uri", "example": "https://auth.clams.tech/v1/device/start" }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "issuer": { "type": "string", "format": "uri", "example": "https://auth.clams.tech" }, "jwks_uri": { "type": "string", "format": "uri", "example": "https://auth.clams.tech/.well-known/jwks.json" }, "token_endpoint": { "type": "string", "format": "uri", "example": "https://auth.clams.tech/v1/token" } } }, "LoginResponse": { "type": "object", "description": "@impl(R-001) @s(S-001) @contract(C-001)\nResponse payload emitted after successful authentication, including the derived subject id.\n\n# Examples\n```\nuse clams_authd::LoginResponse;\nuse clams_identity::{AccessToken, AuthSuccess, Provider, SessionId, UserId};\nuse clams_identity::SubjectId;\n\nlet response = LoginResponse::from(AuthSuccess {\n user_id: UserId::new(\"user-123\"),\n session_id: SessionId::new(\"session-456\"),\n access_token: AccessToken::new(\"token-abc\"),\n subject_id: SubjectId::from_namespaced(&uuid::Uuid::NAMESPACE_URL, b\"user-123\"),\n provider: Provider::Google,\n email: Some(\"user@example.com\".to_owned()),\n email_verified: Some(true),\n});\nassert_eq!(response.session_id(), \"session-456\");\nassert_eq!(response.email(), Some(\"user@example.com\"));\n```", "required": [ "user_id", "session_id", "access_token", "subject_id" ], "properties": { "access_token": { "type": "string", "example": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJzdmMiLCJleHAiOjE3MDAwMDAwMDAsImlhdCI6MTcwMDAwMDAwMCwic2Vzc2lvbl9pZCI6IjAxODkwYjhjLTVjZmQtN2Q1Zi04ZjkwLTNjN2Y0ZjYyZDgwMSIsInN1YiI6Ijg2MmZkNWVkLWFjOWEtNWJmZS05NmYyLWFiMWY1MDFhMmM5OSIsInVzZXJfaWQiOiJ1c2VyLTEyMyJ9.signature" }, "email": { "type": [ "string", "null" ], "example": "user@example.com" }, "email_verified": { "type": [ "boolean", "null" ], "example": true }, "session_id": { "type": "string", "format": "uuid", "example": "01890b8c-5cfd-7d5f-8f90-3c7f4f62d801" }, "subject_id": { "type": "string", "format": "uuid", "example": "862fd5ed-ac9a-5bfe-96f2-ab1f501a2c99" }, "user_id": { "type": "string", "example": "user-123" } } }, "LoginSessionStartRequest": { "type": "object", "description": "Request payload for `POST /v1/web/login/session/start`.", "properties": { "redirect_to": { "type": [ "string", "null" ], "format": "uri", "description": "Optional redirect URL to be surfaced back to the web or desktop app after login.", "example": "clams://callback" } } }, "LoginSessionStartResponse": { "type": "object", "description": "Payload returned by `POST /v1/web/login/session/start`.", "required": [ "login_session_id", "browser_url", "expires_in" ], "properties": { "browser_url": { "type": "string", "format": "uri", "description": "Browser URL to open for the user.", "example": "https://auth.clams.tech/?login_session=0191c0ff-7a5b-7d43-8a0e-75c1a4d7c123" }, "expires_in": { "type": "integer", "format": "int64", "description": "TTL in seconds for the login session.", "example": 600, "minimum": 1 }, "login_session_id": { "type": "string", "format": "uuid", "description": "Generated login session identifier.", "example": "0191c0ff-7a5b-7d43-8a0e-75c1a4d7c123" }, "poll_secret": { "type": [ "string", "null" ], "description": "Client-held proof required when polling the session status.", "example": "qvBdycWQEHzMAwV8V1oxTxb2HAkDsWrZZe-zZmbbFhc", "maxLength": 43, "minLength": 43 } } }, "LoginSessionStatusResponse": { "oneOf": [ { "type": "object", "description": "Session exists but is still pending.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending" ] } } }, { "type": "object", "description": "Session completed successfully and exposes the login response.", "required": [ "login", "status" ], "properties": { "login": { "$ref": "#/components/schemas/LoginResponse" }, "notice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountNoticeResponse" } ] }, "status": { "type": "string", "enum": [ "completed" ] } } }, { "type": "object", "description": "Session failed terminally.", "required": [ "reason", "status" ], "properties": { "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "failed" ] } } }, { "type": "object", "description": "Session is expired or unknown.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "expired" ] } } } ], "description": "Serializable status payload for `/v1/web/login/session/{id}`." }, "OpenApiBeginExistingRootMigrationRequest": { "type": "object", "description": "Request to create a signed automatic existing-root migration challenge.", "required": [ "evidence", "legacy_feedback_bearer" ], "properties": { "evidence": { "$ref": "#/components/schemas/OpenApiExistingRootEnrollmentEvidence" }, "legacy_feedback_bearer": { "type": "string", "example": "feedback-access-token", "writeOnly": true } } }, "OpenApiBillingFractionalCentsResponse": { "type": "object", "description": "Fractional-cent trace returned by flexible invoice responses.", "required": [ "numerator", "denominator" ], "properties": { "denominator": { "type": "integer", "format": "int64", "example": 1, "minimum": 1 }, "numerator": { "type": "integer", "format": "int64", "example": 0, "minimum": 0 } } }, "OpenApiBillingInactiveReason": { "type": "string", "description": "Reasons a billing license can be inactive.", "enum": [ "missing", "payment_pending", "expired", "revoked" ] }, "OpenApiBillingInstanceOwnerResponse": { "type": "object", "description": "Billing owner status for one backend instance.", "required": [ "instance_id", "owner_subject_id", "owner_authorization_revision", "active_key_id", "authorized_at_epoch" ], "properties": { "active_key_id": { "type": "string", "example": "isk_abc123" }, "authorized_at_epoch": { "type": "integer", "format": "int64", "example": 1780435200, "minimum": 0 }, "default_capacity_assignment_revision": { "type": [ "integer", "null" ], "format": "int64", "example": 4, "minimum": 1 }, "default_capacity_owner_subject_id": { "type": [ "string", "null" ], "example": "cfd2e45c-182a-5f77-9f6f-0c87516376b5" }, "default_profile_limit": { "type": [ "integer", "null" ], "format": "int32", "example": 5, "minimum": 1 }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "owner_authorization_revision": { "type": "integer", "format": "int64", "example": 3, "minimum": 1 }, "owner_subject_id": { "type": "string", "example": "cfd2e45c-182a-5f77-9f6f-0c87516376b5" } } }, "OpenApiBillingInvoiceDiscountKind": { "type": "string", "description": "Discount calculation kind returned by flexible invoice responses.", "enum": [ "percent", "fixed_amount", "override_price" ] }, "OpenApiBillingInvoiceDiscountResponse": { "type": "object", "description": "Public discount snapshot returned by flexible v2 invoice responses.", "required": [ "discount_id", "kind", "amount_before_cents", "discount_cents", "amount_after_cents", "dropped_fractional_cent" ], "properties": { "amount_after_cents": { "type": "integer", "format": "int64", "example": 9950, "minimum": 0 }, "amount_before_cents": { "type": "integer", "format": "int64", "example": 19900, "minimum": 0 }, "code": { "type": [ "string", "null" ], "example": "BETA50" }, "discount_cents": { "type": "integer", "format": "int64", "example": 9950, "minimum": 0 }, "discount_id": { "type": "string", "example": "beta_50_once_v1" }, "dropped_fractional_cent": { "$ref": "#/components/schemas/OpenApiBillingFractionalCentsResponse" }, "kind": { "$ref": "#/components/schemas/OpenApiBillingInvoiceDiscountKind" } } }, "OpenApiBillingInvoiceLightningResponse": { "type": "object", "description": "Direct Lightning invoice details returned for Phoenixd-backed invoices.", "required": [ "bolt11_invoice", "lightning_uri", "payment_hash", "requested_sats", "received_sats" ], "properties": { "bolt11_invoice": { "type": "string", "example": "lnbc1990n1p..." }, "lightning_uri": { "type": "string", "example": "lightning:lnbc1990n1p..." }, "payment_hash": { "type": "string", "example": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "quote_expires_at_epoch": { "type": [ "integer", "null" ], "format": "int64", "example": 1780438800, "minimum": 0 }, "received_sats": { "type": "integer", "format": "int64", "example": 0, "minimum": 0 }, "requested_sats": { "type": "integer", "format": "int64", "example": 663334, "minimum": 1 } } }, "OpenApiBillingInvoiceLineKind": { "type": "string", "description": "Line kind returned by flexible invoice responses.", "enum": [ "subject_license", "profile_capacity", "rounding_adjustment", "manual_adjustment" ] }, "OpenApiBillingInvoiceLineResponse": { "type": "object", "description": "Public invoice line snapshot returned by flexible v2 invoice responses.", "required": [ "line_id", "kind", "billing_scope", "plan_id", "offer_id", "price_id", "currency", "quantity", "subtotal_cents", "discount_cents", "tax_cents", "total_cents" ], "properties": { "billing_scope": { "type": "string", "example": "subject:018f7b0b-1111-7000-8000-000000000001" }, "currency": { "type": "string", "example": "USD" }, "discount_cents": { "type": "integer", "format": "int64", "example": 9950, "minimum": 0 }, "kind": { "$ref": "#/components/schemas/OpenApiBillingInvoiceLineKind" }, "line_id": { "type": "string", "example": "line_1" }, "offer_id": { "type": "string", "example": "individual_annual_usd_199_v1" }, "plan_id": { "type": "string", "example": "individual_annual_usd_199" }, "price_id": { "type": "string", "example": "individual_annual_usd_199_v1" }, "proration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiBillingProrationResponse" } ] }, "quantity": { "type": "integer", "format": "int32", "example": 1, "minimum": 1 }, "subtotal_cents": { "type": "integer", "format": "int64", "example": 19900, "minimum": 0 }, "tax_cents": { "type": "integer", "format": "int64", "example": 0, "minimum": 0 }, "total_cents": { "type": "integer", "format": "int64", "example": 9900, "minimum": 0 } } }, "OpenApiBillingInvoiceResponse": { "type": "object", "description": "Public invoice payload returned by billing endpoints.", "required": [ "invoice_id", "settlement_source", "status", "plan_id", "amount_cents", "currency", "subtotal_cents", "discount_total_cents", "pre_round_total_cents", "rounding_adjustment_cents", "invoice_lines", "discounts", "created_at_epoch", "updated_at_epoch" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "example": 19900, "minimum": 0 }, "checkout_acceptance": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiCheckoutAcceptanceSnapshot" } ] }, "created_at_epoch": { "type": "integer", "format": "int64", "example": 1780435100, "minimum": 0 }, "currency": { "type": "string", "example": "USD" }, "discount_total_cents": { "type": "integer", "format": "int64", "example": 9950, "minimum": 0 }, "discounts": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiBillingInvoiceDiscountResponse" } }, "invoice_id": { "type": "string", "example": "019728cc-e88b-7d6e-86dd-5f2b2cb179d4" }, "invoice_lines": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiBillingInvoiceLineResponse" } }, "license_valid_from_epoch": { "type": [ "integer", "null" ], "format": "int64", "example": 1780435200, "minimum": 0 }, "license_valid_until_epoch": { "type": [ "integer", "null" ], "format": "int64", "example": 1811971200, "minimum": 0 }, "lightning": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiBillingInvoiceLightningResponse" } ] }, "paid_at_epoch": { "type": [ "integer", "null" ], "format": "int64", "example": 1780435200, "minimum": 0 }, "payment_method": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiBillingPaymentMethod", "description": "Present for externally settled provider invoices." } ] }, "payment_url": { "type": [ "string", "null" ], "format": "uri", "example": "https://checkout.stripe.com/c/pay/cs_test_..." }, "plan_id": { "type": "string", "example": "individual_annual_usd_199" }, "pre_round_total_cents": { "type": "integer", "format": "int64", "example": 9950, "minimum": 0 }, "provider_checkout_expires_at_epoch": { "type": [ "integer", "null" ], "format": "int64", "example": 1790812800, "minimum": 0 }, "rounding_adjustment_cents": { "type": "integer", "format": "int64", "example": 50, "minimum": 0 }, "settlement_source": { "$ref": "#/components/schemas/OpenApiBillingInvoiceSettlementSource" }, "status": { "$ref": "#/components/schemas/OpenApiBillingInvoiceStatus" }, "subtotal_cents": { "type": "integer", "format": "int64", "example": 19900, "minimum": 0 }, "updated_at_epoch": { "type": "integer", "format": "int64", "example": 1780435200, "minimum": 0 } } }, "OpenApiBillingInvoiceSettlementSource": { "type": "string", "description": "Settlement path expected for a billing invoice.", "enum": [ "provider", "internal" ] }, "OpenApiBillingInvoiceStatus": { "type": "string", "description": "Internal invoice status exposed by billing endpoints.", "enum": [ "created", "provider_created", "open", "processing", "underpaid", "paid", "expired", "failed", "refunded", "webhook_rejected" ] }, "OpenApiBillingLegalResponse": { "type": "object", "description": "Current fully verified legal manifest.", "required": [ "schema_version", "revision", "published_at", "checkout", "report_disclaimer" ], "properties": { "checkout": { "$ref": "#/components/schemas/OpenApiCheckoutPolicy" }, "published_at": { "type": "string", "example": "2026-07-15T18:00:00Z" }, "report_disclaimer": { "$ref": "#/components/schemas/OpenApiReportDisclaimerPolicy" }, "revision": { "type": "integer", "format": "int64", "example": 12, "minimum": 1 }, "schema_version": { "type": "integer", "format": "int32", "example": 1, "minimum": 0 } } }, "OpenApiBillingLicenseProfileCapacityResponse": { "type": "object", "description": "Profile-capacity status for an instance-bound license response.", "required": [ "instance_id", "profile_capacity_limit", "entitlement_revision", "valid_until_epoch" ], "properties": { "active_profile_reservation_count": { "type": [ "integer", "null" ], "format": "int32", "example": 1, "minimum": 0 }, "coverage_periods": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiProfileCapacityCoveragePeriod" }, "description": "Current and future paid capacity periods when the covered limit changes." }, "coverage_valid_until_epoch": { "type": [ "integer", "null" ], "format": "int64", "description": "Furthest continuous paid coverage for the current capacity limit.", "example": 1843507200, "minimum": 0 }, "entitlement_revision": { "type": "integer", "format": "int64", "example": 11, "minimum": 0 }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "profile_capacity_limit": { "type": "integer", "format": "int32", "example": 3, "minimum": 0 }, "valid_until_epoch": { "type": "integer", "format": "int64", "example": 1811971200, "minimum": 0 } } }, "OpenApiBillingLicenseResponse": { "type": "object", "description": "Current license and latest-invoice state for the authenticated subject.", "required": [ "state", "plan_id", "amount_cents", "currency" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "example": 19900, "minimum": 0 }, "coverage_valid_until_epoch": { "type": [ "integer", "null" ], "format": "int64", "description": "Final end of current and future paid license coverage.", "example": 1843507200, "minimum": 0 }, "currency": { "type": "string", "example": "USD" }, "inactive_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiBillingInactiveReason" } ] }, "latest_invoice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiBillingInvoiceResponse", "description": "Latest provider invoice for the subject; may be license or profile-capacity billing." } ] }, "plan_id": { "type": "string", "example": "individual_annual_usd_199" }, "profile_capacity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiBillingLicenseProfileCapacityResponse" } ] }, "state": { "$ref": "#/components/schemas/OpenApiBillingLicenseState" }, "valid_until_epoch": { "type": [ "integer", "null" ], "format": "int64", "description": "Active license expiry, or prior license expiry when the license is inactive.", "example": 1811971200, "minimum": 0 } } }, "OpenApiBillingLicenseState": { "type": "string", "description": "License states exposed to clients.", "enum": [ "active", "license_required", "payment_pending", "license_expired" ] }, "OpenApiBillingOfferEntitlementKind": { "type": "string", "description": "Entitlement kind granted by a billing offer.", "enum": [ "subject_license", "instance_capacity" ] }, "OpenApiBillingOfferInterval": { "type": "string", "description": "Billing interval for a public offer.", "enum": [ "annual" ] }, "OpenApiBillingOfferPriceTier": { "type": "object", "description": "One public offer price tier.", "required": [ "first_unit", "unit_amount_cents" ], "properties": { "first_unit": { "type": "integer", "format": "int32", "example": 1, "minimum": 1 }, "last_unit": { "type": [ "integer", "null" ], "format": "int32", "example": 100, "minimum": 0 }, "unit_amount_cents": { "type": "integer", "format": "int64", "example": 4900, "minimum": 0 } } }, "OpenApiBillingOfferPricingModel": { "type": "string", "description": "Pricing model for a public offer.", "enum": [ "flat", "per_unit", "package", "graduated_tiers", "volume_tiers" ] }, "OpenApiBillingOfferResponse": { "type": "object", "description": "One public billing offer.", "required": [ "offer_id", "plan_id", "plan_version", "display_name", "entitlement_kind", "price_id", "currency", "billing_interval", "pricing_model", "unit_label", "base_amount_cents", "tiers", "min_quantity", "self_service_allowed", "discount_available", "creates_subject_license", "creates_instance_capacity", "checkout_enabled" ], "properties": { "applies_to_current_instance": { "type": [ "boolean", "null" ] }, "base_amount_cents": { "type": "integer", "format": "int64", "example": 19900, "minimum": 0 }, "billing_interval": { "$ref": "#/components/schemas/OpenApiBillingOfferInterval" }, "checkout_enabled": { "type": "boolean" }, "creates_instance_capacity": { "type": "boolean" }, "creates_subject_license": { "type": "boolean" }, "currency": { "type": "string", "example": "USD" }, "disabled_reason": { "type": [ "string", "null" ] }, "discount_available": { "type": "boolean" }, "display_name": { "type": "string", "example": "Clams Individual Annual" }, "entitlement_kind": { "$ref": "#/components/schemas/OpenApiBillingOfferEntitlementKind" }, "max_quantity": { "type": [ "integer", "null" ], "format": "int32", "example": 1, "minimum": 0 }, "min_quantity": { "type": "integer", "format": "int32", "example": 1, "minimum": 0 }, "offer_id": { "type": "string", "example": "individual_annual_usd_199_v1" }, "plan_id": { "type": "string", "example": "individual_annual_usd_199" }, "plan_version": { "type": "integer", "format": "int32", "example": 1, "minimum": 0 }, "price_id": { "type": "string", "example": "individual_annual_usd_199_v1" }, "pricing_model": { "$ref": "#/components/schemas/OpenApiBillingOfferPricingModel" }, "self_service_allowed": { "type": "boolean" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiBillingOfferPriceTier" } }, "unit_label": { "type": "string", "example": "seat" } } }, "OpenApiBillingOffersResponse": { "type": "object", "description": "Public billing offers response.", "required": [ "catalog_snapshot_version", "offers" ], "properties": { "catalog_snapshot_version": { "type": "integer", "format": "int32", "example": 1, "minimum": 0 }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiBillingOfferResponse" } } } }, "OpenApiBillingPaymentMethod": { "type": "string", "description": "Public payment methods supported for hosted annual-license checkout.", "enum": [ "card", "lightning" ] }, "OpenApiBillingProrationResponse": { "type": "object", "description": "Proration trace returned by flexible billing quote and invoice responses.", "required": [ "full_amount_cents", "remaining_seconds", "full_period_seconds", "amount_cents", "dropped_fractional_cent" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "example": 2450, "minimum": 0 }, "dropped_fractional_cent": { "$ref": "#/components/schemas/OpenApiBillingFractionalCentsResponse" }, "full_amount_cents": { "type": "integer", "format": "int64", "example": 4900, "minimum": 0 }, "full_period_seconds": { "type": "integer", "format": "int64", "example": 31536000, "minimum": 1 }, "remaining_seconds": { "type": "integer", "format": "int64", "example": 15768000, "minimum": 0 } } }, "OpenApiBillingWebhookResponse": { "type": "object", "description": "Webhook processing response.", "required": [ "accepted_events" ], "properties": { "accepted_events": { "type": "integer", "example": 1, "minimum": 0 } } }, "OpenApiCheckoutAcceptanceRequest": { "type": "object", "description": "Client-supplied atomic legal acceptance payload for checkout invoice creation.", "required": [ "accepted_checkout_policy_id", "auto_renewal_consent" ], "properties": { "accepted_checkout_policy_id": { "type": "string", "example": "checkout_policy_example" }, "account_company": { "type": [ "string", "null" ], "example": "Example Pty Ltd" }, "auto_renewal_consent": { "type": "boolean", "example": false } } }, "OpenApiCheckoutAcceptanceSnapshot": { "type": "object", "description": "Durable checkout acceptance facts returned with invoices.", "required": [ "accepted", "accepted_at_epoch", "manifest_revision", "manifest_published_at", "checkout_policy_id", "acceptance_text", "renewal_policy", "auto_renewal_consent", "terms", "privacy" ], "properties": { "acceptance_text": { "type": "string" }, "accepted": { "type": "boolean" }, "accepted_at_epoch": { "type": "integer", "format": "int64", "minimum": 0 }, "account_company": { "type": [ "string", "null" ] }, "auto_renewal_consent": { "type": "boolean" }, "checkout_policy_id": { "type": "string", "example": "checkout_policy_example" }, "client_ip": { "type": [ "string", "null" ] }, "manifest_published_at": { "type": "string", "example": "2026-07-15T18:00:00Z" }, "manifest_revision": { "type": "integer", "format": "int64", "example": 12, "minimum": 1 }, "privacy": { "$ref": "#/components/schemas/OpenApiLegalDocumentSnapshot" }, "renewal_policy": { "$ref": "#/components/schemas/OpenApiCheckoutRenewalPolicy" }, "terms": { "$ref": "#/components/schemas/OpenApiLegalDocumentSnapshot" }, "user_agent": { "type": [ "string", "null" ] } } }, "OpenApiCheckoutCreationPendingCode": { "type": "string", "description": "Stable code for an identical checkout still being created.", "enum": [ "E409-BILLING-CHECKOUT-PENDING" ] }, "OpenApiCheckoutCreationPendingError": { "type": "object", "description": "Conflict returned while an identical checkout is still being created.", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/OpenApiCheckoutCreationPendingCode" }, "details": { "type": [ "object", "null" ], "additionalProperties": {}, "propertyNames": { "type": "string" } }, "message": { "type": "string", "example": "billing checkout creation is still pending" }, "request_id": { "type": [ "string", "null" ], "example": "req_01HZX2Y6K5X8YH9WJ6QW6A7B8C" }, "retry_after_seconds": { "type": [ "integer", "null" ], "format": "int64", "example": 2, "minimum": 1 } } }, "OpenApiCheckoutPolicy": { "type": "object", "description": "Complete atomic checkout policy.", "required": [ "policy_id", "acceptance_text", "renewal_policy", "terms", "privacy" ], "properties": { "acceptance_text": { "type": "string" }, "policy_id": { "type": "string", "example": "checkout_policy_example" }, "privacy": { "$ref": "#/components/schemas/OpenApiLegalDocumentSnapshot" }, "renewal_policy": { "$ref": "#/components/schemas/OpenApiCheckoutRenewalPolicy" }, "terms": { "$ref": "#/components/schemas/OpenApiLegalDocumentSnapshot" } } }, "OpenApiCheckoutRenewalPolicy": { "type": "string", "description": "Renewal policy selected by the verified manifest.", "enum": [ "manual_renewal", "one_time_annual_license", "auto_renewing_subscription" ] }, "OpenApiCompleteExistingRootMigrationRequest": { "type": "object", "description": "Request to complete an automatic existing-root migration challenge.", "required": [ "evidence", "challenge_id", "instance_binding_proof" ], "properties": { "challenge_id": { "type": "string", "example": "ibc_018f7b0b" }, "evidence": { "$ref": "#/components/schemas/OpenApiExistingRootEnrollmentEvidence" }, "instance_binding_proof": { "type": "string", "example": "{\"challenge_id\":\"ibc_018f7b0b\",\"signature\":\"base64url\"}" } } }, "OpenApiConnectionOAuthAccessTokenRequest": { "type": "object", "description": "Request body for obtaining a short-lived access token from a hosted broker credential ref.", "required": [ "provider_key", "credential_ref" ], "properties": { "credential_ref": { "type": "string", "example": "cred_abc123" }, "provider_key": { "type": "string", "example": "mercury" } } }, "OpenApiConnectionOAuthAccessTokenResponse": { "type": "object", "description": "Response body containing a short-lived provider access token.", "required": [ "token_type", "access_token", "expires_in" ], "properties": { "access_token": { "type": "string", "format": "password", "example": "provider-access-token" }, "expires_in": { "type": "integer", "format": "int64", "example": 300, "minimum": 1 }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "token_type": { "type": "string", "example": "Bearer" } } }, "OpenApiConnectionOAuthCredentialStatusResponse": { "type": "object", "description": "Non-secret hosted credential status.", "required": [ "provider_key", "credential_ref", "status" ], "properties": { "access_token_expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-01T00:00:00Z" }, "credential_ref": { "type": "string", "example": "cred_abc123" }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "provider_key": { "type": "string", "example": "mercury" }, "refresh_token_expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-12-31T00:00:00Z" }, "status": { "type": "string", "example": "connected" }, "status_message": { "type": [ "string", "null" ] } } }, "OpenApiConnectionOAuthStartRequest": { "type": "object", "description": "Request body for starting a hosted connection OAuth broker flow.", "required": [ "connection_id" ], "properties": { "connection_id": { "type": "string", "example": "01890c10-0000-7000-8000-000000000701" }, "requested_scopes": { "type": "array", "items": { "type": "string" } } } }, "OpenApiConnectionOAuthStartResponse": { "type": "object", "description": "Response body for a hosted connection OAuth broker start.", "required": [ "authorization_url", "state", "expires_in", "mode" ], "properties": { "authorization_url": { "type": "string", "format": "uri", "example": "https://provider.example/oauth/authorize?..." }, "credential_ref": { "type": [ "string", "null" ], "example": "cred_abc123" }, "expires_in": { "type": "integer", "format": "int64", "example": 600, "minimum": 1 }, "mode": { "type": "string", "example": "hosted_broker" }, "state": { "type": "string", "example": "state_abc123" } } }, "OpenApiCreateBillingInvoiceRequest": { "type": "object", "description": "Request body for creating or reusing a hosted billing invoice.", "required": [ "payment_method", "renew_instance_capacity", "success_url", "cancel_url", "checkout_acceptance" ], "properties": { "cancel_url": { "type": "string", "format": "uri", "example": "https://auth.clams.tech/v1/billing/cancel" }, "checkout_acceptance": { "$ref": "#/components/schemas/OpenApiCheckoutAcceptanceRequest" }, "discount_code": { "type": [ "string", "null" ], "example": "BETA50" }, "instance_binding_challenge_id": { "type": [ "string", "null" ], "example": "ibc_018f7b0b" }, "instance_binding_proof": { "type": [ "string", "null" ], "example": "base64url-signature" }, "instance_id": { "type": [ "string", "null" ], "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "offer_id": { "type": [ "string", "null" ], "example": "individual_annual_usd_199_v1" }, "payment_method": { "$ref": "#/components/schemas/OpenApiBillingPaymentMethod" }, "quantity": { "type": [ "integer", "null" ], "format": "int32", "example": 1, "minimum": 1 }, "renew_instance_capacity": { "type": "boolean", "example": true }, "success_url": { "type": "string", "format": "uri", "example": "https://auth.clams.tech/v1/billing/return" } } }, "OpenApiCreateInstanceBindingChallengeRequest": { "type": "object", "description": "Request body for creating an instance-binding challenge.", "required": [ "instance_id", "audience", "action" ], "properties": { "action": { "$ref": "#/components/schemas/OpenApiInstanceBindingChallengeAction" }, "audience": { "type": "string", "example": "svc" }, "bootstrap_key": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiInstanceBindingBootstrapKey" } ] }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "refresh_token": { "type": [ "string", "null" ], "example": "svc-refresh-token", "writeOnly": true }, "request_fingerprint": { "type": [ "string", "null" ], "example": "sha256:canonical-request-fingerprint" } } }, "OpenApiCreateInvoiceConflictResponse": { "oneOf": [ { "$ref": "#/components/schemas/OpenApiLegalAcceptanceStaleError", "description": "The caller accepted a superseded checkout policy." }, { "$ref": "#/components/schemas/OpenApiCheckoutCreationPendingError", "description": "Another identical checkout is still being created." } ], "description": "Conflict returned when invoice creation must be retried." }, "OpenApiCreateOAuthClientRequest": { "type": "object", "description": "Request payload for `POST /v1/oauth-clients`.", "properties": { "audience": { "$ref": "#/components/schemas/OpenApiMachineAudience", "description": "Requested audience for the created client (typically `rates` or `feedback`)." } } }, "OpenApiCreateOAuthClientResponse": { "type": "object", "description": "Response payload for `POST /v1/oauth-clients`.", "required": [ "client_id", "client_secret", "audience", "created_at" ], "properties": { "audience": { "$ref": "#/components/schemas/OpenApiMachineAudience" }, "client_id": { "type": "string", "example": "cli_123e4567-e89b-12d3-a456-426614174000" }, "client_secret": { "type": "string", "example": "wkzmUl4MM3wWOlRmCaHsCq17ttD4xDXZiT5399qom9k", "maxLength": 43, "minLength": 43 }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp for creation time.", "example": "2026-02-07T12:34:56Z" } } }, "OpenApiCreateProfileCapacityReservationRequest": { "type": "object", "description": "Request body for creating an authd profile-capacity reservation.", "required": [ "instance_id", "profile_id", "instance_binding_challenge_id", "instance_binding_proof" ], "properties": { "instance_binding_challenge_id": { "type": "string", "example": "ibc_018f7b0b" }, "instance_binding_proof": { "type": "string", "example": "{\"challenge_id\":\"ibc_018f7b0b\",\"signature\":\"base64url\"}" }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "profile_id": { "type": "string", "format": "uuid", "example": "018f7b0b-2222-7000-8000-000000000001" } } }, "OpenApiErrorEnvelope": { "type": "object", "description": "Error payload returned by authd routes.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code for programmatic handling.", "example": "E401-AUTH-FAILED" }, "details": { "type": [ "object", "null" ], "description": "Optional error details for debugging.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "message": { "type": "string", "description": "Human-readable error message.", "example": "not authorized" }, "request_id": { "type": [ "string", "null" ], "description": "Optional request identifier for support.", "example": "req_01HZX2Y6K5X8YH9WJ6QW6A7B8C" }, "retry_after_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional retry hint in seconds.", "example": 10, "minimum": 1 } } }, "OpenApiExistingRootEnrollmentEvidence": { "type": "object", "description": "Sanitized evidence describing a beta-era local root.", "required": [ "protocol_version", "instance_id", "workspace_count", "non_deleted_profile_count", "legacy_credentials_present", "imported_billing_history_present", "local_snapshot_hash", "key_id", "public_key", "public_key_digest", "key_revision", "key_created_at_epoch" ], "properties": { "imported_billing_history_present": { "type": "boolean" }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "key_created_at_epoch": { "type": "integer", "format": "int64", "example": 1780435200, "minimum": 0 }, "key_id": { "type": "string", "example": "isk_018f7b0b" }, "key_revision": { "type": "integer", "format": "int64", "example": 1, "minimum": 1 }, "legacy_credentials_present": { "type": "boolean" }, "local_snapshot_hash": { "type": "string", "example": "base64url-sha256-canonical-root-snapshot" }, "non_deleted_profile_count": { "type": "integer", "format": "int32", "example": 4, "minimum": 1 }, "protocol_version": { "type": "integer", "format": "int32", "example": 1, "minimum": 1 }, "public_key": { "type": "string", "example": "base64url-ed25519-public-key" }, "public_key_digest": { "type": "string", "example": "base64url-sha256-public-key-digest" }, "workspace_count": { "type": "integer", "format": "int32", "example": 1, "minimum": 1 } } }, "OpenApiExistingRootMigrationResponse": { "type": "object", "description": "Approved automatic existing-root migration.", "required": [ "instance_id", "subject_id", "migration_id", "grandfathered_profile_limit", "already_authorized" ], "properties": { "already_authorized": { "type": "boolean" }, "grandfathered_profile_limit": { "type": "integer", "format": "int32", "example": 4, "minimum": 1 }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "migration_id": { "type": "string", "example": "migration_bf2d4b1e" }, "subject_id": { "type": "string", "example": "cfd2e45c-182a-5f77-9f6f-0c87516376b5" } } }, "OpenApiInstanceBindingBootstrapKey": { "type": "object", "description": "Public key metadata for first local instance enrollment.", "required": [ "key_id", "public_key", "public_key_digest", "key_revision", "created_at_epoch" ], "properties": { "created_at_epoch": { "type": "integer", "format": "int64", "example": 1780435200, "minimum": 0 }, "key_id": { "type": "string", "example": "isk_abc123" }, "key_revision": { "type": "integer", "format": "int64", "example": 1, "minimum": 0 }, "public_key": { "type": "string", "example": "base64url-ed25519-public-key" }, "public_key_digest": { "type": "string", "example": "base64url-sha256-public-key-digest" } } }, "OpenApiInstanceBindingChallengeAction": { "type": "string", "description": "Operation bound to an instance-binding challenge.", "enum": [ "svc_exchange", "svc_refresh", "capacity_checkout", "capacity_reservation", "reservation_commit", "reservation_release", "owner_transfer" ] }, "OpenApiInstanceBindingChallengeResponse": { "type": "object", "description": "Response body for a newly issued instance-binding challenge.", "required": [ "challenge_id", "nonce", "expires_at_epoch" ], "properties": { "challenge_id": { "type": "string", "example": "ibc_018f7b0b-1111-7000-8000-000000000001" }, "expires_at_epoch": { "type": "integer", "format": "int64", "example": 1780435500, "minimum": 0 }, "nonce": { "type": "string", "example": "base64url-nonce" }, "proof_authorization_token": { "type": [ "string", "null" ] } } }, "OpenApiJwk": { "type": "object", "description": "Minimal JWK representation for Ed25519 keys used by authd.", "required": [ "kty", "alg", "crv", "kid", "x" ], "properties": { "alg": { "type": "string", "example": "EdDSA" }, "crv": { "type": "string", "example": "Ed25519" }, "kid": { "type": "string" }, "kty": { "type": "string", "example": "OKP" }, "x": { "type": "string", "description": "Public key coordinate (`x`) encoded with base64url (no padding)." } } }, "OpenApiJwksSet": { "type": "object", "description": "JWKS document returned by `GET /.well-known/jwks.json`.", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiJwk" } } } }, "OpenApiLegalAcceptanceStaleError": { "type": "object", "description": "Atomic stale-policy conflict returned before any invoice reservation.", "required": [ "code", "message", "current_checkout" ], "properties": { "code": { "type": "string", "example": "legal_acceptance_stale" }, "current_checkout": { "$ref": "#/components/schemas/OpenApiCheckoutPolicy" }, "message": { "type": "string", "example": "The checkout legal policy changed before invoice creation." } } }, "OpenApiLegalDocumentSnapshot": { "type": "object", "description": "Complete immutable legal document snapshot.", "required": [ "document_id", "last_updated", "current_url", "archive_url", "canonical_body_url", "sha256" ], "properties": { "archive_url": { "type": "string", "format": "uri", "example": "https://clams.tech/legal/terms/2026-07-15/" }, "canonical_body_url": { "type": "string", "format": "uri", "example": "https://clams.tech/legal/terms/2026-07-15/body.txt" }, "current_url": { "type": "string", "format": "uri", "example": "https://clams.tech/terms/" }, "document_id": { "type": "string", "example": "terms_of_use_example" }, "effective_date": { "type": [ "string", "null" ], "example": "2025-11-10" }, "last_updated": { "type": "string", "example": "2026-07-15" }, "sha256": { "type": "string", "example": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } }, "OpenApiMachineAudience": { "type": "string", "description": "Token audiences supported for machine-to-machine credentials.", "enum": [ "rates", "feedback" ] }, "OpenApiPhoenixdCheckoutStatusResponse": { "type": "object", "description": "Public checkout status for an authd-hosted Phoenixd Lightning invoice.", "required": [ "invoice_id", "status", "paid", "amount_cents", "currency", "requested_sats", "received_sats" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "example": 19900, "minimum": 0 }, "currency": { "type": "string", "example": "USD" }, "expires_at_epoch": { "type": [ "integer", "null" ], "format": "int64", "example": 1800000000, "minimum": 0 }, "invoice_id": { "type": "string", "example": "019728cc-e88b-7d6e-86dd-5f2b2cb179d4" }, "paid": { "type": "boolean", "example": false }, "received_sats": { "type": "integer", "format": "int64", "example": 0, "minimum": 0 }, "requested_sats": { "type": "integer", "format": "int64", "example": 180000, "minimum": 1 }, "status": { "$ref": "#/components/schemas/OpenApiBillingInvoiceStatus" } } }, "OpenApiProfileCapacityCoveragePeriod": { "type": "object", "description": "One continuous paid profile-capacity coverage period.", "required": [ "valid_from_epoch", "valid_until_epoch", "profile_capacity_limit" ], "properties": { "profile_capacity_limit": { "type": "integer", "format": "int32", "example": 5, "minimum": 0 }, "valid_from_epoch": { "type": "integer", "format": "int64", "example": 1811971200, "minimum": 0 }, "valid_until_epoch": { "type": "integer", "format": "int64", "example": 1843507200, "minimum": 0 } } }, "OpenApiProfileCapacityQuoteResponse": { "type": "object", "description": "Public profile-capacity quote response.", "required": [ "offer_id", "price_id", "instance_id", "quantity", "currency", "tiers", "subtotal_cents", "pre_round_total_cents", "rounding_adjustment_cents", "total_cents", "profile_capacity_before", "profile_capacity_after", "entitlement_revision", "valid_until_epoch" ], "properties": { "currency": { "type": "string", "example": "USD" }, "entitlement_revision": { "type": "integer", "format": "int64", "example": 11, "minimum": 0 }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "offer_id": { "type": "string", "example": "extra_profiles_annual_usd_v1" }, "pre_round_total_cents": { "type": "integer", "format": "int64", "example": 4900, "minimum": 0 }, "price_id": { "type": "string", "example": "extra_profiles_annual_usd_v1" }, "profile_capacity_after": { "type": "integer", "format": "int32", "example": 4, "minimum": 0 }, "profile_capacity_before": { "type": "integer", "format": "int32", "example": 3, "minimum": 0 }, "profiles_in_use": { "type": [ "integer", "null" ], "format": "int32", "example": 3, "minimum": 0 }, "proration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenApiBillingProrationResponse" } ] }, "quantity": { "type": "integer", "format": "int32", "example": 1, "minimum": 1 }, "rounding_adjustment_cents": { "type": "integer", "format": "int64", "example": 0, "minimum": 0 }, "subtotal_cents": { "type": "integer", "format": "int64", "example": 4900, "minimum": 0 }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiBillingOfferPriceTier" } }, "total_cents": { "type": "integer", "format": "int64", "example": 4900, "minimum": 0 }, "valid_until_epoch": { "type": "integer", "format": "int64", "example": 1811971200, "minimum": 0 } } }, "OpenApiProfileCapacityReservationResponse": { "type": "object", "description": "Response body for an authd profile-capacity reservation.", "required": [ "reservation_id", "instance_id", "profile_id", "state", "expires_at_epoch", "active_capacity_limit", "active_reservation_count" ], "properties": { "active_capacity_limit": { "type": "integer", "format": "int32", "example": 3, "minimum": 0 }, "active_reservation_count": { "type": "integer", "format": "int32", "example": 1, "minimum": 0 }, "committed_at_epoch": { "type": [ "integer", "null" ], "format": "int64", "example": 1780435200, "minimum": 0 }, "expires_at_epoch": { "type": "integer", "format": "int64", "example": 1780435500, "minimum": 0 }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "profile_id": { "type": "string", "format": "uuid", "example": "018f7b0b-2222-7000-8000-000000000001" }, "released_at_epoch": { "type": [ "integer", "null" ], "format": "int64", "example": 1780435300, "minimum": 0 }, "reservation_id": { "type": "string", "example": "pcr_018f7b0b" }, "state": { "$ref": "#/components/schemas/OpenApiProfileCapacityReservationState" } } }, "OpenApiProfileCapacityReservationState": { "type": "string", "description": "Authd profile-capacity reservation lifecycle state.", "enum": [ "reserved", "committed", "released", "expired" ] }, "OpenApiQuoteProfileCapacityRequest": { "type": "object", "description": "Request body for dry-running a profile-capacity checkout quote.", "required": [ "quantity", "instance_id", "instance_binding_challenge_id", "instance_binding_proof" ], "properties": { "instance_binding_challenge_id": { "type": "string", "example": "ibc_018f7b0b" }, "instance_binding_proof": { "type": "string", "example": "base64url-signature" }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "quantity": { "type": "integer", "format": "int32", "example": 1, "minimum": 1 } } }, "OpenApiReportDisclaimerPolicy": { "type": "object", "description": "Complete report disclaimer policy.", "required": [ "notice_id", "text", "document" ], "properties": { "document": { "$ref": "#/components/schemas/OpenApiLegalDocumentSnapshot" }, "notice_id": { "type": "string", "example": "report_disclaimer_example" }, "text": { "type": "string" } } }, "OpenApiTokenRequest": { "oneOf": [ { "type": "object", "description": "Refresh token grant (rotating refresh token).", "required": [ "refresh_token", "audience", "grant_type" ], "properties": { "audience": { "$ref": "#/components/schemas/RefreshGrantAudience", "description": "Requested audience for the returned access token." }, "billing_capabilities": { "type": "array", "items": { "type": "string" }, "description": "Client-declared optional capabilities, such as `profile_capacity_enforced` or\n`account_notices_v1` for interactive `svc` refresh notices." }, "billing_protocol_version": { "type": [ "integer", "null" ], "format": "int32", "description": "Client-declared flexible billing protocol version.", "minimum": 0 }, "grant_type": { "type": "string", "enum": [ "refresh_token" ] }, "instance_binding_challenge_id": { "type": [ "string", "null" ], "description": "Server-issued instance binding challenge id." }, "instance_binding_proof": { "type": [ "string", "null" ], "description": "Serialized instance binding proof." }, "instance_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Backend instance id for future instance-bound SVC refresh." }, "refresh_token": { "type": "string", "description": "Opaque refresh token string.", "example": "wkzmUl4MM3wWOlRmCaHsCq17ttD4xDXZiT5399qom9k", "maxLength": 43, "minLength": 43 } } }, { "type": "object", "description": "Client credentials grant (machine-to-machine).", "required": [ "client_id", "client_secret", "audience", "grant_type" ], "properties": { "audience": { "$ref": "#/components/schemas/OpenApiMachineAudience" }, "client_id": { "type": "string", "example": "cli_123e4567-e89b-12d3-a456-426614174000" }, "client_secret": { "type": "string", "example": "wkzmUl4MM3wWOlRmCaHsCq17ttD4xDXZiT5399qom9k", "maxLength": 43, "minLength": 43 }, "grant_type": { "type": "string", "enum": [ "client_credentials" ] } } } ], "description": "Request payload for `POST /v1/token`.\n\nNote: the server internally parses these requests into richer types that also validate\n`grant_type` and enforce per-grant invariants." }, "OpenApiTransferBillingInstanceOwnerRequest": { "type": "object", "description": "Request body for self-service billing owner transfer.", "required": [ "new_owner_subject_id", "instance_binding_challenge_id", "instance_binding_proof", "request_fingerprint" ], "properties": { "instance_binding_challenge_id": { "type": "string", "example": "ibc_018f7b0b" }, "instance_binding_proof": { "type": "string", "example": "{\"challenge_id\":\"ibc_018f7b0b\",\"signature\":\"base64url\"}" }, "new_owner_subject_id": { "type": "string", "example": "c6f4d9e1-b6e8-5a6d-9bb9-1f50644625db" }, "request_fingerprint": { "type": "string", "example": "sha256:canonical-transfer-fingerprint" } } }, "OpenApiTransferBillingInstanceOwnerResponse": { "type": "object", "description": "Response body for a completed billing owner transfer.", "required": [ "instance_id", "previous_owner_subject_id", "owner_subject_id", "owner_authorization_revision", "transferred_at_epoch" ], "properties": { "default_capacity_assignment_revision": { "type": [ "integer", "null" ], "format": "int64", "example": 5, "minimum": 1 }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "owner_authorization_revision": { "type": "integer", "format": "int64", "example": 1, "minimum": 1 }, "owner_subject_id": { "type": "string", "example": "c6f4d9e1-b6e8-5a6d-9bb9-1f50644625db" }, "previous_owner_subject_id": { "type": "string", "example": "cfd2e45c-182a-5f77-9f6f-0c87516376b5" }, "transferred_at_epoch": { "type": "integer", "format": "int64", "example": 1780435200, "minimum": 0 } } }, "OpenApiUpdateProfileCapacityReservationRequest": { "type": "object", "description": "Request body for committing or releasing an authd profile-capacity reservation.", "required": [ "instance_id", "instance_binding_challenge_id", "instance_binding_proof" ], "properties": { "instance_binding_challenge_id": { "type": "string", "example": "ibc_018f7b0b" }, "instance_binding_proof": { "type": "string", "example": "{\"challenge_id\":\"ibc_018f7b0b\",\"signature\":\"base64url\"}" }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" } } }, "OpenApiValidateProfileCapacityRevisionRequest": { "type": "object", "description": "Request body for validating a token profile-capacity revision.", "required": [ "instance_id", "entitlement_revision" ], "properties": { "entitlement_revision": { "type": "integer", "format": "int64", "example": 11, "minimum": 1 }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" } } }, "OpenApiValidateProfileCapacityRevisionResponse": { "type": "object", "description": "Response body for token profile-capacity revision validation.", "required": [ "instance_id", "submitted_entitlement_revision", "current_entitlement_revision", "token_profile_limit", "active_capacity_limit", "is_current", "cache_valid_until_epoch" ], "properties": { "active_capacity_limit": { "type": "integer", "format": "int32", "example": 5, "minimum": 0 }, "cache_valid_until_epoch": { "type": "integer", "format": "int64", "example": 1780435500, "minimum": 0 }, "current_entitlement_revision": { "type": "integer", "format": "int64", "example": 11, "minimum": 0 }, "instance_id": { "type": "string", "format": "uuid", "example": "018f7b0b-1111-7000-8000-000000000001" }, "is_current": { "type": "boolean" }, "submitted_entitlement_revision": { "type": "integer", "format": "int64", "example": 11, "minimum": 1 }, "token_profile_limit": { "type": "integer", "format": "int32", "example": 5, "minimum": 0 } } }, "RefreshGrantAudience": { "type": "string", "description": "@impl(R-004) @s(S-004,S-010)\nSupported access token audiences for the refresh grant.\n\nNew variants must be appended to the end of this enum. Reordering variants or inserting a new\nvariant before the end breaks bincode decoding of persisted OAuth client records.", "enum": [ "svc", "rates", "feedback" ] }, "RefreshGrantResponse": { "type": "object", "description": "@impl(R-010) @s(S-010)\nSuccessful response payload emitted by the refresh grant.", "required": [ "user_id", "session_id", "access_token", "refresh_token", "audience" ], "properties": { "access_token": { "type": "string", "example": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJyYXRlcyIsImV4cCI6MTcwMDAwMDAwMCwiaWF0IjoxNzAwMDAwMDAwLCJzZXNzaW9uX2lkIjoiMDE4OTBiOGMtNWNmZC03ZDVmLThmOTAtM2M3ZjRmNjJkODAxIiwic3ViIjoiODYyZmQ1ZWQtYWM5YS01YmZlLTk2ZjItYWIxZjUwMWEyYzk5IiwidXNlcl9pZCI6InVzZXItMTIzIn0.signature" }, "audience": { "$ref": "#/components/schemas/RefreshGrantAudience" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/AccountNoticeResponse" } }, "refresh_token": { "type": "string", "example": "wkzmUl4MM3wWOlRmCaHsCq17ttD4xDXZiT5399qom9k", "maxLength": 43, "minLength": 43 }, "session_id": { "type": "string", "format": "uuid", "example": "01890b8c-5cfd-7d5f-8f90-3c7f4f62d801" }, "user_id": { "type": "string", "example": "user-123" } } }, "TokenExchangeRequest": { "type": "object", "description": "@impl(S-015)\nRequest payload for `/v1/token/exchange`.\n\nThis type models the RFC 8693 token exchange request. It enforces that\nthe `subject_token` (<= 8,192 chars) and `subject_token_type` (<= 256 chars)\nfields are trimmed, non-empty, and below conservative upper bounds to guard\nagainst unbounded payloads.\n\n# Examples\n```\n# use clams_authd::token::{RefreshGrantAudience, TokenExchangeRequest};\nlet request = TokenExchangeRequest::new(\n \"svc-access-token\",\n \"urn:ietf:params:oauth:token-type:access_token\",\n RefreshGrantAudience::Svc,\n Some(\"profile email\".to_owned()),\n);\nassert_eq!(request.subject_token_type(), \"urn:ietf:params:oauth:token-type:access_token\");\nassert_eq!(request.audience(), RefreshGrantAudience::Svc);\nassert_eq!(request.scope(), Some(\"profile email\"));\n```", "required": [ "subject_token", "subject_token_type", "audience" ], "properties": { "audience": { "$ref": "#/components/schemas/RefreshGrantAudience" }, "billing_capabilities": { "type": "array", "items": { "type": "string" }, "default": [] }, "billing_protocol_version": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "instance_binding_challenge_id": { "type": [ "string", "null" ] }, "instance_binding_proof": { "type": [ "string", "null" ] }, "instance_id": { "type": [ "string", "null" ], "format": "uuid" }, "scope": { "type": [ "string", "null" ], "example": "profile email" }, "subject_token": { "type": "string", "example": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJzdmMiLCJleHAiOjE3MDAwMDAwMDAsImlhdCI6MTcwMDAwMDAwMCwic2Vzc2lvbl9pZCI6IjAxODkwYjhjLTVjZmQtN2Q1Zi04ZjkwLTNjN2Y0ZjYyZDgwMSIsInN1YiI6Ijg2MmZkNWVkLWFjOWEtNWJmZS05NmYyLWFiMWY1MDFhMmM5OSIsInVzZXJfaWQiOiJ1c2VyLTEyMyJ9.signature", "maxLength": 8192 }, "subject_token_type": { "type": "string", "example": "urn:ietf:params:oauth:token-type:access_token", "maxLength": 256 } } }, "TokenResponse": { "oneOf": [ { "$ref": "#/components/schemas/RefreshGrantResponse" }, { "$ref": "#/components/schemas/ClientCredentialsGrantResponse" } ], "description": "Union response emitted by `/v1/token`." }, "WhoamiResponse": { "type": "object", "description": "@impl(R-001) @s(S-001) @contract(C-004)\nSerializable payload returned by `GET /v1/auth/whoami`, exposing both user and subject ids.", "required": [ "user_id", "subject_id" ], "properties": { "subject_id": { "type": "string", "format": "uuid", "example": "862fd5ed-ac9a-5bfe-96f2-ab1f501a2c99" }, "user_id": { "type": "string", "example": "user-123" } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "Login", "description": "Browser-based login session handshake for CLI/MCP flows" }, { "name": "Tokens", "description": "Token exchange and refresh" }, { "name": "OAuth Clients", "description": "Client credentials provisioning" }, { "name": "Connection OAuth", "description": "Hosted broker endpoints for provider-backed connection authorization" }, { "name": "Account", "description": "Authenticated account/session helpers" }, { "name": "Billing", "description": "License status, invoice creation, and provider webhooks" }, { "name": "Discovery", "description": "JWKS and OIDC discovery documents" } ] }