{ "openapi": "3.1.0", "info": { "title": "Presence API", "version": "0.1.0", "summary": "Human verification for consequential decisions", "description": "Public wire contract shared by the Presence SDKs. Tenant credentials are\nserver-side secrets. Browser and mobile clients receive narrow session or\ninvitation credentials instead.\n", "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" } }, "servers": [ { "url": "https://presence.decionis.com", "description": "Presence API" } ], "tags": [ { "name": "Sandbox", "description": "Deterministic first-run scenarios that are permanently labelled as fixtures." }, { "name": "Sessions", "description": "Narrow credentials and state for one action-bound verification." }, { "name": "Decisions", "description": "Policy evaluation and signed verdict creation." }, { "name": "Dossiers", "description": "Retrieval and independent verification of sealed evidence." }, { "name": "Verification Requests", "description": "Intent-bound human verification: create a request for a named subject,\nhand off the invitation, and poll until the request reaches a terminal\nstatus with a sealed receipt.\n" }, { "name": "Authority Requests", "description": "Asynchronous human authority after a Decionis ESCALATE. Human approval\nproduces evidence only; execution remains held until Decionis returns a\nfinal AUTHORIZED authority decision.\n" }, { "name": "Enforcement", "description": "The enforcement contract's decision question — the minimum proof for\none action right now. Adapters enforce the disposition; they never\nre-derive policy.\n" }, { "name": "Accounts", "description": "Email-first sign-in, product sessions, sandbox provisioning, and\ninvitations for the Decionis identity authority. Public authentication\nendpoints answer with an identical status and shape for every email so\nthey cannot be used as an account directory.\n" } ], "paths": { "/v1/sandbox/scenarios/{scenario}": { "post": { "operationId": "runSandboxScenario", "tags": [ "Sandbox" ], "summary": "Run a deterministic, signed sandbox fixture", "description": "Available only for sandbox tenants on deployments that explicitly\nenable fixtures. The signed payload is labelled\n`evidence_class: sandbox_fixture`; it is not production evidence.\n", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "scenario", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SandboxScenario" } } ], "responses": { "200": { "description": "Fixture decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxFixtureResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/sessions": { "post": { "operationId": "createSession", "tags": [ "Sessions" ], "summary": "Open a verification session for one action", "security": [ { "tenantBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionContext" } } } }, "responses": { "201": { "description": "Session and narrow browser credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/decide": { "post": { "operationId": "decide", "tags": [ "Decisions" ], "summary": "Evaluate an attested verification request", "security": [ { "tenantBearer": [] }, { "sessionBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideRequest" } } } }, "responses": { "200": { "description": "Effective verdict and signed dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/dossiers/{dossierId}": { "get": { "operationId": "getDossier", "tags": [ "Dossiers" ], "summary": "Retrieve one tenant-scoped dossier record", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/DossierId" } ], "responses": { "200": { "description": "Dossier record", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/dossiers/{dossierId}/verify": { "get": { "operationId": "verifyDossier", "tags": [ "Dossiers" ], "summary": "Recompute a dossier signature and chain link", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/DossierId" } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DossierVerification" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/.well-known/presence-dossier-jwks.json": { "get": { "operationId": "getDossierPublicKeys", "tags": [ "Dossiers" ], "summary": "Get active and retired dossier verification keys", "security": [], "responses": { "200": { "description": "JSON Web Key Set", "content": { "application/json": { "schema": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/check": { "post": { "operationId": "check", "tags": [ "Enforcement" ], "summary": "Ask for the minimum proof required for one action", "description": "Returns the disposition to enforce — PASS, CHALLENGE, STEP_UP, or\nDENY — with the assurance tiers that back it and a bounded lifetime.\nThe `token` under test is the browser's Session Token (the payload,\nnot the caller's credential); the tenant key authenticates the call,\nwhich is why this endpoint belongs on the server. Fail closed: treat\nany transport error or `503 check_unavailable` as a step-up, never\nas a PASS.\n", "security": [ { "tenantBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRequest" } } } }, "responses": { "200": { "description": "The decision to enforce", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceDecision" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/verification-requests": { "post": { "operationId": "createVerificationRequest", "tags": [ "Verification Requests" ], "summary": "Start an intent-bound verification for a named subject", "description": "Binds the exact action — copy, values, and requirements — into an\nimmutable envelope, seals a request dossier, and returns the narrow\ninvitation credential the intended subject uses to view and answer\nthis request. Retrying with the same `Idempotency-Key` replays the\noriginal creation with `replayed: true` and status 200.\n", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVerificationRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of a previously created request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedIntentVerification" } } } }, "201": { "description": "Request created, invitation credential issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedIntentVerification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/verification-requests/{requestId}": { "get": { "operationId": "getVerificationRequest", "tags": [ "Verification Requests" ], "summary": "Read the current status of a verification request", "description": "Poll this endpoint until the request reaches a terminal status:\nALLOWED, BLOCKED, or ESCALATED (each carrying `result` and a sealed\nreceipt dossier), or EXPIRED / CANCELLED. Requests live between 30\nand 600 seconds, so polling every few seconds is expected; there is\nno long-poll variant. `verification.requested`, `decision.evaluated`,\nand `escalation.opened` webhook events (see `webhooks`) remove the\nneed to poll tightly.\n", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Current actor-scoped projection of the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationRequest" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "cancelVerificationRequest", "tags": [ "Verification Requests" ], "summary": "Cancel a pending verification request", "description": "Cancelling fails closed: the request moves to CANCELLED and an\nautonomous BLOCK receipt is sealed, so a cancelled action can never\nbe mistaken for an approved one.\n", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "The cancelled request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationRequest" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/authority-requests": { "post": { "operationId": "createAuthorityRequest", "tags": [ "Authority Requests" ], "summary": "Record and optionally deliver a Decionis authority requirement", "description": "Validates the requirement through the trusted Decionis adapter,\nrecomputes the action digest, resolves the subject server-side, and\nseals the immutable request. Availability depends on the rollout mode:\ndisabled performs no writes; record stops after sealing; deliver also\nroutes to one device at a time; enforce additionally permits final\nDecionis re-evaluation after proof.\n", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuthorityRequest" } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedAuthorityRequest" } } } }, "201": { "description": "Authority request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedAuthorityRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/authority-requests/{requestId}": { "get": { "operationId": "getAuthorityRequest", "tags": [ "Authority Requests" ], "summary": "Read ceremony and Decionis release states separately", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Current authority projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorityRequest" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "cancelAuthorityRequest", "tags": [ "Authority Requests" ], "summary": "Cancel a non-terminal human ceremony", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Cancelled or already-terminal request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorityRequest" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/authority-requests/{requestId}/retry-release": { "post": { "operationId": "retryAuthorityRelease", "tags": [ "Authority Requests" ], "summary": "Retry final Decionis re-evaluation without repeating human proof", "security": [ { "tenantBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Current release state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorityRequest" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/mobile/authority-requests/{requestId}": { "get": { "operationId": "getMobileAuthorityRequest", "tags": [ "Authority Requests" ], "summary": "Fetch one authority envelope through an actor-bound device", "security": [ { "mobileDeviceId": [], "mobileDeviceRequestId": [], "mobileDeviceTimestamp": [], "mobileDeviceSignature": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Actor-bound authority request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorityRequest" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/mobile/authority-requests/{requestId}/presented": { "post": { "operationId": "presentMobileAuthorityRequest", "tags": [ "Authority Requests" ], "summary": "Record that the exact authority context was displayed", "security": [ { "mobileDeviceId": [], "mobileDeviceRequestId": [], "mobileDeviceTimestamp": [], "mobileDeviceSignature": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Viewed authority request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorityRequest" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/mobile/authority-requests/{requestId}/respond": { "post": { "operationId": "respondToMobileAuthorityRequest", "tags": [ "Authority Requests" ], "summary": "Submit action-bound platform evidence for approval or denial", "security": [ { "mobileDeviceId": [], "mobileDeviceRequestId": [], "mobileDeviceTimestamp": [], "mobileDeviceSignature": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitAuthorityResponse" } } } }, "responses": { "200": { "description": "Proof state and, in enforce mode, Decionis release state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorityRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/auth/discover": { "post": { "operationId": "discoverAccount", "tags": [ "Accounts" ], "summary": "Start email-first sign-in", "description": "Resolves how an email authenticates. The response status, shape, and\ncopy are identical for every address — known, unknown, invited, or\ndisabled; 400 is returned for malformed input only.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryRequest" } } } }, "responses": { "200": { "description": "Discovery session and the methods to offer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/sessions": { "post": { "operationId": "createAuthSession", "tags": [ "Accounts" ], "summary": "Authenticate a discovery with a password or passkey", "description": "Completes the PASSWORD or PASSKEY method for a live discovery and\nmints a single-use identity assertion. Every authentication failure\nanswers a uniform 401 `invalid_credentials` with comparable timing.\nFederated methods start at `POST /v1/auth/oidc/start` instead.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionRequest" } } } }, "responses": { "200": { "description": "Identity assertion for the product-session exchange", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/oidc/start": { "post": { "operationId": "startOidcAuthentication", "tags": [ "Accounts" ], "summary": "Start federated provider authentication", "description": "Returns a credential-free HTTPS provider authorization URL. Public\nGoogle, Microsoft, and GitHub methods may start directly with product\ncontext; the Account authority resolves the verified provider identity\nafter callback. A discovery-bound request remains available and is\nrequired for enterprise SSO. Only deployment-configured providers are\naccepted.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcStartRequest" } } } }, "responses": { "200": { "description": "Provider authorization URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcStartResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/oidc/callback": { "get": { "operationId": "handleOidcCallback", "tags": [ "Accounts" ], "summary": "Provider redirect target", "description": "Validates the provider response and redirects to the web app with a\none-time completion code (`poc_…`, single-use, 60 s). Tokens are never\ndelivered in the redirect URL itself.\n", "security": [], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "302": { "description": "Redirect to the web completion page with a one-time code", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/oidc/complete": { "post": { "operationId": "completeOidcAuthentication", "tags": [ "Accounts" ], "summary": "Exchange the one-time OIDC completion code", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcCompleteRequest" } } } }, "responses": { "200": { "description": "Identity assertion for the product-session exchange", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/email-verifications": { "post": { "operationId": "requestEmailVerification", "tags": [ "Accounts" ], "summary": "Send a verification email for a discovery", "description": "Answers 202 whether or not an email was sent, so the endpoint cannot\nconfirm account existence. The link carries a single-use `dvt_` token\nthat expires after 20 minutes.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationRequest" } } } }, "responses": { "202": { "description": "Accepted — identical for every address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountVerificationAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/email-verifications/confirm": { "post": { "operationId": "confirmEmailVerification", "tags": [ "Accounts" ], "summary": "Confirm a verification link", "description": "Marks the mailbox verified, single-use. When the confirmed link is a\nSIGNUP verification for an address with no established account,\n`identity_assertion` + `expires_in` are returned — mailbox proof is\nthat user's initial identity and feeds `POST /v1/provisioning/sandbox`.\nAn established user never receives an assertion from an email link.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationConfirmRequest" } } } }, "responses": { "200": { "description": "Email verified; the sign-in or signup flow resumes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationConfirmResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/passkey/options": { "post": { "operationId": "createPasskeyAssertionOptions", "tags": [ "Accounts" ], "summary": "Mint WebAuthn assertion options for a discovery", "description": "Returns standard WebAuthn request options for the resident-key /\ndiscoverable flow: challenge, rpId, and userVerification with an\nALWAYS-EMPTY allowCredentials, so the response shape is identical for\nknown and unknown emails. The challenge is single-use and bound to the\ndiscovery session. Field names inside `options` are the WebAuthn wire\nspelling (camelCase) by specification.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptionsRequest" } } } }, "responses": { "200": { "description": "Assertion request options for navigator.credentials.get", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptionsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/invitations/{token}/preview": { "get": { "operationId": "previewInvitation", "tags": [ "Accounts" ], "summary": "Preview an invitation by its token", "description": "Possession of the `dit_` token gates this preview. Unknown, revoked,\nand expired invitations all answer an indistinguishable 404.\n", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^dit_[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Human-readable invitation preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationPreview" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/invitations/{token}/accept": { "post": { "operationId": "acceptInvitation", "tags": [ "Accounts" ], "summary": "Accept an invitation as a verified identity", "description": "The verified email behind the Bearer assertion must match the\ninvitation's email (case-insensitively). Acceptance is single-use and\nnever mints an entitlement: a workspace whose Presence entitlement has\nlapsed answers 409 `entitlement_missing`. Unknown, revoked, and\nexpired invitations all answer an indistinguishable 404.\n", "security": [ { "identityAssertionBearer": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^dit_[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Membership created; the workspace is ready to select", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-sessions/exchange": { "post": { "operationId": "exchangeProductSession", "tags": [ "Accounts" ], "summary": "Exchange an identity assertion for a product session", "description": "One authorized workspace issues immediately; several return\n`workspace_selection_required` with named entries, answered by\nrepeating the exchange with `workspace_id`. A workspace outside the\ncaller's authorized set answers 404 — existence is never confirmed.\nNo workspace with an active Presence entitlement answers 403\n`no_presence_workspace` with an optional `sandbox_eligible` hint.\n", "security": [ { "identityAssertionBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSessionExchangeRequest" } } } }, "responses": { "200": { "description": "Issued session or workspace selection", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/IssuedProductSession" }, { "$ref": "#/components/schemas/WorkspaceSelectionRequired" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-sessions/refresh": { "post": { "operationId": "refreshProductSession", "tags": [ "Accounts" ], "summary": "Rotate a product session", "description": "Every grant supersedes the presented refresh token. Presenting a\nsuperseded token again revokes the whole session as replay.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSessionRefreshRequest" } } } }, "responses": { "200": { "description": "Fresh access/refresh pair for the same workspace binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSessionRefreshResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-sessions/revoke": { "post": { "operationId": "revokeProductSession", "tags": [ "Accounts" ], "summary": "Revoke a product session", "description": "Revokes by refresh token in the body, or by the access token presented\nas the Bearer credential. Succeeds identically whether or not the\nsession was live.\n", "security": [ {}, { "productSessionBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSessionRevokeRequest" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/provisioning/sandbox": { "post": { "operationId": "provisionSandbox", "tags": [ "Accounts" ], "summary": "Provision a sandbox workspace idempotently", "description": "Starts (or resumes) the sandbox provisioning saga for the verified\nidentity presented as the Bearer assertion. The same Idempotency-Key\nreplays the same run; retries resume from the last completed step and\nnever create duplicates.\n", "security": [ { "identityAssertionBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Replayed or completed run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisioningRun" } } } }, "202": { "description": "Run accepted and progressing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisioningRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/provisioning/sandbox/{runId}": { "get": { "operationId": "getProvisioningRun", "tags": [ "Accounts" ], "summary": "Poll a provisioning run", "description": "Callers see only their own runs; anything else answers 404.", "security": [ { "identityAssertionBearer": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prv_[a-f0-9]{24}$" } } ], "responses": { "200": { "description": "Current run state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisioningRun" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": { "domainEvent": { "post": { "operationId": "receiveDomainEvent", "summary": "Signed delivery of a Presence domain event", "description": "Presence delivers `verification.requested`, `decision.evaluated`, and\n`escalation.opened` events to a tenant-configured HTTPS endpoint.\nEvery delivery carries a `vero-timestamp` header and a\n`vero-signature` header: the hex HMAC-SHA256 of\n`\"{vero-timestamp}.{raw request body}\"` under the tenant's webhook\nsecret. Verify the signature over the exact raw bytes before parsing,\nand reject stale timestamps to close the replay window.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainEventDelivery" } } } }, "responses": { "200": { "description": "Delivery acknowledged; any 2xx stops retries." } } } } }, "components": { "securitySchemes": { "tenantBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "presence_sk_…", "description": "Tenant credential. Keep it on a trusted server." }, "sessionBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "presence_st_…", "description": "Short-lived credential scoped to one verification session." }, "identityAssertionBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "presence_pi_…", "description": "Single-use identity assertion minted after authentication and\nexchanged for a product session. Short-lived; never stored.\n" }, "productSessionBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "presence_ps_…", "description": "Product session access token. Delivered to browsers only inside\nHttpOnly cookies by the web proxy; claims are transport, and\nauthorization is always re-read server-side from membership records.\n" }, "mobileDeviceId": { "type": "apiKey", "in": "header", "name": "vero-device-id" }, "mobileDeviceRequestId": { "type": "apiKey", "in": "header", "name": "vero-device-request-id" }, "mobileDeviceTimestamp": { "type": "apiKey", "in": "header", "name": "vero-device-timestamp" }, "mobileDeviceSignature": { "type": "apiKey", "in": "header", "name": "vero-device-signature", "description": "P-256 signature over method, path, timestamp, request id, and exact body." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key reused when the same action is retried.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" } }, "DossierId": { "name": "dossierId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, "RequestId": { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Credential or environment is not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Gone": { "description": "Resource expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Idempotency or rollout conflict", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unavailable": { "description": "Decision dependency unavailable; the action remains held", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "Public request rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "SandboxScenario": { "type": "string", "enum": [ "allow", "block", "escalate" ] }, "SandboxFixtureResult": { "type": "object", "additionalProperties": false, "required": [ "sandbox_fixture", "scenario", "policy_verdict", "effective_verdict", "decision" ], "properties": { "sandbox_fixture": { "type": "boolean", "const": true }, "scenario": { "$ref": "#/components/schemas/SandboxScenario" }, "policy_verdict": { "$ref": "#/components/schemas/Verdict" }, "effective_verdict": { "$ref": "#/components/schemas/Verdict" }, "decision": { "allOf": [ { "$ref": "#/components/schemas/DecideResponse" }, { "type": "object", "required": [ "evidence_class" ], "properties": { "evidence_class": { "type": "string", "const": "sandbox_fixture" } } } ] } } }, "ErrorResponse": { "type": "object", "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "const": "error" }, "reason": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "ActionContext": { "type": "object", "additionalProperties": false, "required": [ "intent", "surface", "actor_id", "target_resource_id" ], "properties": { "intent": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "minLength": 1 }, "actor_id": { "type": "string", "minLength": 1 }, "target_resource_id": { "type": "string", "minLength": 1 }, "provider_event_id": { "type": "string" }, "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "recipient_iban": { "type": "string" } } }, "CreatedSession": { "type": "object", "required": [ "session_id", "session_token", "session_token_expires_in", "nonce", "created_at", "status" ], "properties": { "session_id": { "type": "string" }, "session_token": { "type": "string" }, "session_token_expires_in": { "type": "integer", "minimum": 1 }, "nonce": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" } } }, "DecideRequest": { "type": "object", "additionalProperties": false, "required": [ "request_id", "session_id", "timestamp", "action_context", "gate_1_state_admission", "gate_2_execution_authority" ], "properties": { "request_id": { "type": "string" }, "session_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "action_context": { "$ref": "#/components/schemas/ActionContext" }, "gate_1_state_admission": { "type": "object", "description": "Server-verified state admission evidence.", "additionalProperties": true }, "gate_2_execution_authority": { "type": "object", "description": "Transient liveness and authenticity signals. Raw media is forbidden.", "additionalProperties": true } } }, "Verdict": { "type": "string", "enum": [ "AUTHORIZED", "RESTRAIN", "ESCALATE", "BLOCKED" ] }, "DecideResponse": { "type": "object", "required": [ "status", "verdict", "execution_token", "evaluated_at", "policy_evaluation", "decision_dossier" ], "properties": { "status": { "type": "string", "enum": [ "success", "error" ] }, "evidence_class": { "type": "string", "enum": [ "sandbox_fixture" ] }, "verdict": { "$ref": "#/components/schemas/Verdict" }, "execution_token": { "type": [ "string", "null" ] }, "evaluated_at": { "type": "string", "format": "date-time" }, "latency_ms": { "type": "number", "minimum": 0 }, "policy_evaluation": { "type": "object", "additionalProperties": true }, "escalation_context": { "type": "object", "additionalProperties": true }, "enforcement": { "$ref": "#/components/schemas/EnforcementOutcome" }, "decision_dossier": { "$ref": "#/components/schemas/DecisionDossier" }, "verification_bundle": { "$ref": "#/components/schemas/VerificationBundle" } } }, "EnforcementOutcome": { "type": "object", "required": [ "mode", "effective_verdict", "true_verdict", "downgraded", "kill_switch_active" ], "properties": { "mode": { "type": "string", "enum": [ "SHADOW", "RESTRAIN_ONLY", "ENFORCE_HIGH_STAKES", "ENFORCE" ] }, "effective_verdict": { "$ref": "#/components/schemas/Verdict" }, "true_verdict": { "$ref": "#/components/schemas/Verdict" }, "downgraded": { "type": "boolean" }, "kill_switch_active": { "type": "boolean" } } }, "DecisionDossier": { "type": "object", "required": [ "dossier_id", "previous_chain_hash", "chain_hash", "algorithm", "public_key_id", "signature" ], "properties": { "dossier_id": { "type": "string" }, "previous_chain_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "chain_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "algorithm": { "type": "string", "const": "Ed25519" }, "public_key_id": { "type": "string" }, "signature": { "type": "string" } } }, "VerificationBundle": { "type": "object", "required": [ "bundle_version", "dossier_id", "kind", "algorithm", "public_key_id", "previous_chain_hash", "chain_hash", "signature", "sealed_payload", "public_keys_url", "verifier_url" ], "properties": { "bundle_version": { "type": "string", "const": "vero.dossier.verification_bundle/1" }, "dossier_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "decision", "override", "governance", "intent" ] }, "algorithm": { "type": "string", "const": "Ed25519" }, "public_key_id": { "type": "string" }, "previous_chain_hash": { "type": "string" }, "chain_hash": { "type": "string" }, "signature": { "type": "string" }, "sealed_payload": {}, "public_keys_url": { "type": "string", "format": "uri" }, "verifier_url": { "type": "string", "format": "uri" } } }, "DossierVerification": { "type": "object", "required": [ "dossier_id", "signature_valid", "chain_valid", "valid" ], "properties": { "dossier_id": { "type": "string" }, "signature_valid": { "type": "boolean" }, "chain_valid": { "type": "boolean" }, "valid": { "type": "boolean" } } }, "AccountAuthMethod": { "type": "string", "enum": [ "PASSKEY", "PASSWORD", "MICROSOFT_OIDC", "GOOGLE_OIDC", "GITHUB_OAUTH", "ENTERPRISE_SSO" ] }, "AccountRole": { "type": "string", "enum": [ "owner", "admin", "security_analyst", "developer", "billing" ] }, "AccountEnvironment": { "type": "string", "enum": [ "sandbox", "production" ] }, "AccountAccepted": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "const": "success" } } }, "AccountVerificationAccepted": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "const": "accepted" } } }, "AccountWorkspaceMembership": { "type": "object", "additionalProperties": false, "required": [ "org_name", "workspace_name", "environment", "role", "workspace_id" ], "properties": { "org_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "workspace_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "environment": { "$ref": "#/components/schemas/AccountEnvironment" }, "role": { "$ref": "#/components/schemas/AccountRole" }, "workspace_id": { "type": "string", "pattern": "^ten_[a-f0-9]{20}$", "description": "Selection round-trip only; the UI never displays it." } } }, "DiscoveryRequest": { "type": "object", "additionalProperties": false, "required": [ "email", "product" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 254 }, "product": { "type": "string", "const": "presence" }, "return_url": { "type": "string", "format": "uri", "maxLength": 2000 } } }, "DiscoveryResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "discovery_id", "next_step", "available_methods", "expires_at" ], "properties": { "status": { "type": "string", "const": "success" }, "discovery_id": { "type": "string", "pattern": "^dsc_[a-f0-9]{24}$" }, "next_step": { "type": "string", "const": "AUTHENTICATE" }, "available_methods": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/AccountAuthMethod" } }, "expires_at": { "type": "string", "format": "date-time" } } }, "AuthSessionRequest": { "type": "object", "additionalProperties": false, "required": [ "discovery_id", "method" ], "description": "`method: PASSWORD` requires `password`; `method: PASSKEY` requires\n`assertion`. OIDC methods are rejected here.\n", "properties": { "discovery_id": { "type": "string", "pattern": "^dsc_[a-f0-9]{24}$" }, "method": { "$ref": "#/components/schemas/AccountAuthMethod" }, "password": { "type": "string", "minLength": 1, "maxLength": 1024 }, "assertion": { "type": "object", "description": "WebAuthn authentication response, validated server-side.", "additionalProperties": true } } }, "AuthSessionResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "identity_assertion", "expires_in" ], "properties": { "status": { "type": "string", "const": "success" }, "identity_assertion": { "type": "string", "pattern": "^presence_pi_[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "expires_in": { "type": "integer", "minimum": 1 } } }, "OidcStartRequest": { "type": "object", "additionalProperties": false, "properties": { "discovery_id": { "type": "string", "pattern": "^dsc_[a-f0-9]{24}$" }, "method": { "type": "string", "enum": [ "MICROSOFT_OIDC", "GOOGLE_OIDC", "GITHUB_OAUTH", "ENTERPRISE_SSO" ] }, "product": { "type": "string", "const": "presence" }, "return_url": { "type": "string", "format": "uri", "maxLength": 2000 } }, "oneOf": [ { "required": [ "discovery_id", "method" ], "not": { "properties": { "product": {} }, "required": [ "product" ] } }, { "required": [ "method", "product" ], "properties": { "method": { "enum": [ "MICROSOFT_OIDC", "GOOGLE_OIDC", "GITHUB_OAUTH" ] } }, "not": { "properties": { "discovery_id": {} }, "required": [ "discovery_id" ] } } ] }, "OidcStartResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "authorization_url" ], "properties": { "status": { "type": "string", "const": "success" }, "authorization_url": { "type": "string", "format": "uri" } } }, "OidcCompleteRequest": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^poc_[A-Za-z0-9_-]{32,100}$", "description": "One-time completion code from the callback redirect." } } }, "EmailVerificationRequest": { "type": "object", "additionalProperties": false, "required": [ "discovery_id" ], "properties": { "discovery_id": { "type": "string", "pattern": "^dsc_[a-f0-9]{24}$" } } }, "EmailVerificationConfirmRequest": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^dvt_[A-Za-z0-9_-]{43}$" } } }, "EmailVerificationConfirmResponse": { "type": "object", "additionalProperties": false, "required": [ "status" ], "description": "`identity_assertion` and `expires_in` appear together exactly when a\nsignup verification establishes the initial identity for an address\nwith no established account; otherwise the response carries `status`\nalone.\n", "properties": { "status": { "type": "string", "const": "success" }, "identity_assertion": { "type": "string", "pattern": "^presence_pi_[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "expires_in": { "type": "integer", "minimum": 1 } } }, "PasskeyOptionsRequest": { "type": "object", "additionalProperties": false, "required": [ "discovery_id" ], "properties": { "discovery_id": { "type": "string", "pattern": "^dsc_[a-f0-9]{24}$" } } }, "PasskeyRequestOptions": { "type": "object", "additionalProperties": false, "required": [ "challenge" ], "description": "Standard WebAuthn PublicKeyCredentialRequestOptionsJSON (camelCase by\nspecification). allowCredentials is always empty — the discoverable\nflow keeps the shape identical for known and unknown emails.\n", "properties": { "challenge": { "type": "string", "minLength": 1 }, "timeout": { "type": "integer", "minimum": 1 }, "rpId": { "type": "string", "minLength": 1 }, "allowCredentials": { "type": "array", "maxItems": 0, "items": {} }, "userVerification": { "type": "string", "enum": [ "required", "preferred", "discouraged" ] }, "extensions": { "type": "object", "additionalProperties": true }, "hints": { "type": "array", "items": { "type": "string" } } } }, "PasskeyOptionsResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "options" ], "properties": { "status": { "type": "string", "const": "success" }, "options": { "$ref": "#/components/schemas/PasskeyRequestOptions" } } }, "InvitationAccepted": { "type": "object", "additionalProperties": false, "required": [ "status", "workspace_id" ], "properties": { "status": { "type": "string", "const": "success" }, "workspace_id": { "type": "string", "pattern": "^ten_[a-f0-9]{20}$" } } }, "InvitationPreview": { "type": "object", "additionalProperties": false, "required": [ "org_name", "workspace_name", "role", "expires_at" ], "properties": { "org_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "workspace_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "$ref": "#/components/schemas/AccountRole" }, "expires_at": { "type": "string", "format": "date-time" } } }, "ProductSessionExchangeRequest": { "type": "object", "additionalProperties": false, "required": [ "product" ], "properties": { "product": { "type": "string", "const": "presence" }, "workspace_id": { "type": "string", "pattern": "^ten_[a-f0-9]{20}$", "description": "Sent only when answering workspace_selection_required." }, "return_url": { "type": "string", "format": "uri", "maxLength": 2000 } } }, "IssuedProductSession": { "type": "object", "additionalProperties": false, "required": [ "status", "access_token", "expires_in", "refresh_token", "refresh_expires_in", "workspace" ], "properties": { "status": { "type": "string", "const": "issued" }, "access_token": { "type": "string", "pattern": "^presence_ps_[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "expires_in": { "type": "integer", "minimum": 1 }, "refresh_token": { "type": "string", "pattern": "^presence_pr_[A-Za-z0-9_-]{43,128}$" }, "refresh_expires_in": { "type": "integer", "minimum": 1 }, "workspace": { "$ref": "#/components/schemas/AccountWorkspaceMembership" }, "return_url": { "type": "string", "format": "uri", "maxLength": 2000 } } }, "WorkspaceSelectionRequired": { "type": "object", "additionalProperties": false, "required": [ "status", "memberships" ], "properties": { "status": { "type": "string", "const": "workspace_selection_required" }, "memberships": { "type": "array", "minItems": 2, "items": { "$ref": "#/components/schemas/AccountWorkspaceMembership" } } } }, "ProductSessionRefreshRequest": { "type": "object", "additionalProperties": false, "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string", "pattern": "^presence_pr_[A-Za-z0-9_-]{43,128}$" } } }, "ProductSessionRefreshResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "access_token", "expires_in", "refresh_token", "refresh_expires_in" ], "properties": { "status": { "type": "string", "const": "issued" }, "access_token": { "type": "string", "pattern": "^presence_ps_[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "expires_in": { "type": "integer", "minimum": 1 }, "refresh_token": { "type": "string", "pattern": "^presence_pr_[A-Za-z0-9_-]{43,128}$" }, "refresh_expires_in": { "type": "integer", "minimum": 1 } } }, "ProductSessionRevokeRequest": { "type": "object", "additionalProperties": false, "properties": { "refresh_token": { "type": "string", "pattern": "^presence_pr_[A-Za-z0-9_-]{43,128}$" } } }, "ProvisioningState": { "type": "string", "enum": [ "IDENTITY_CREATED", "EMAIL_VERIFICATION_PENDING", "EMAIL_VERIFIED", "ORGANIZATION_RESOLVED", "WORKSPACE_PROVISIONING", "WORKSPACE_PROVISIONED", "PRESENCE_ENTITLEMENT_PENDING", "PRESENCE_ENTITLED", "ACTIVATION_PENDING", "ACTIVE", "SUSPENDED", "PROVISIONING_FAILED" ] }, "ProvisionedWorkspace": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "workspace_name", "environment" ], "properties": { "workspace_id": { "type": "string", "pattern": "^ten_[a-f0-9]{20}$" }, "workspace_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "environment": { "$ref": "#/components/schemas/AccountEnvironment" } } }, "ProvisioningRun": { "type": "object", "additionalProperties": false, "required": [ "status", "run_id", "state", "correlation_id" ], "properties": { "status": { "type": "string", "const": "success" }, "run_id": { "type": "string", "pattern": "^prv_[a-f0-9]{24}$" }, "state": { "$ref": "#/components/schemas/ProvisioningState" }, "correlation_id": { "type": "string", "pattern": "^REF-[a-f0-9]{12}$", "description": "Support reference surfaced to the user on failure." }, "replayed": { "type": "boolean" }, "failure_reason": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Present exactly when state is PROVISIONING_FAILED." }, "workspace": { "$ref": "#/components/schemas/ProvisionedWorkspace" } } }, "CheckContext": { "type": "object", "additionalProperties": false, "description": "Optional action context; keys are camelCase on this wire.", "properties": { "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "accountAgeDays": { "type": "integer", "minimum": 0 }, "authenticated": { "type": "boolean" } } }, "CheckRequest": { "type": "object", "additionalProperties": false, "required": [ "token", "intent" ], "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The browser's Session Token — the payload under test." }, "intent": { "type": "string", "minLength": 1, "maxLength": 200 }, "context": { "$ref": "#/components/schemas/CheckContext" } } }, "Disposition": { "type": "string", "enum": [ "PASS", "CHALLENGE", "STEP_UP", "DENY" ], "description": "What the caller must enforce." }, "RequiredProof": { "type": "string", "enum": [ "challenge", "webauthn", "liveness" ], "description": "The proof rung a step-up requires; present only for CHALLENGE / STEP_UP." }, "Assurance": { "type": "object", "additionalProperties": false, "required": [ "behavioral", "webauthn", "liveness" ], "properties": { "behavioral": { "type": "boolean", "description": "The passive behavioral tier affirmatively cleared." }, "webauthn": { "type": "boolean", "description": "A server-verified WebAuthn assertion is pinned to the session." }, "liveness": { "type": "boolean", "description": "A scored liveness pass — or an AUTHORIZED decide — backs the session." } } }, "PresenceDecision": { "type": "object", "required": [ "decision_id", "disposition", "assurance", "score", "ttl", "expires_at" ], "properties": { "decision_id": { "type": "string", "minLength": 1 }, "disposition": { "$ref": "#/components/schemas/Disposition" }, "required_proof": { "$ref": "#/components/schemas/RequiredProof" }, "assurance": { "$ref": "#/components/schemas/Assurance" }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Behavioral risk that fed the decision (0 = human, 1 = adverse)." }, "ttl": { "type": "integer", "minimum": 0, "description": "Seconds the caller may cache this decision." }, "expires_at": { "type": "string", "description": "Absolute expiry (ISO 8601), issuance + ttl." }, "proof": { "type": "string", "description": "Reserved for a locally verifiable signed assertion; not yet issued." } } }, "CreateIntentOriginator": { "type": "object", "additionalProperties": false, "required": [ "organization_name" ], "description": "The party shown to the subject as the source of the request. Identity\nprovenance is assigned server-side from the authenticated ingress path\nand cannot be supplied by the caller.\n", "properties": { "organization_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "actor_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "IntentDisplayField": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "value" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "IntentPresentation": { "type": "object", "additionalProperties": false, "required": [ "locale", "title", "description", "display_fields" ], "description": "Exact copy and values the subject must see before platform authentication.", "properties": { "locale": { "type": "string", "minLength": 2, "maxLength": 35, "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 1, "maxLength": 1000 }, "display_fields": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/IntentDisplayField" } } } }, "VerificationLevel": { "type": "string", "enum": [ "STANDARD", "HIGH_CONFIDENCE" ] }, "VerificationMethod": { "type": "string", "enum": [ "WEBAUTHN", "MOBILE_DEVICE", "ACTIVE_LIVENESS" ] }, "MobileDevicePolicy": { "type": "string", "enum": [ "WEB_OR_JIT_DEVICE", "MANAGED_DEVICE_REQUIRED" ] }, "VerificationRequirements": { "type": "object", "additionalProperties": false, "required": [ "level", "methods", "hardware_pki_required", "disallow_virtual_cameras" ], "properties": { "level": { "$ref": "#/components/schemas/VerificationLevel" }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "$ref": "#/components/schemas/VerificationMethod" } }, "hardware_pki_required": { "type": "boolean" }, "disallow_virtual_cameras": { "type": "boolean" }, "mobile_device_policy": { "$ref": "#/components/schemas/MobileDevicePolicy" }, "trusted_ip_regions": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Coarse regions allowed by policy; raw IP addresses never enter the envelope.", "items": { "type": "string", "minLength": 1, "maxLength": 64 } } } }, "CreateVerificationRequest": { "type": "object", "additionalProperties": false, "required": [ "action_context", "originator", "presentation", "verification_requirements" ], "properties": { "action_context": { "$ref": "#/components/schemas/ActionContext" }, "originator": { "$ref": "#/components/schemas/CreateIntentOriginator" }, "presentation": { "$ref": "#/components/schemas/IntentPresentation" }, "verification_requirements": { "$ref": "#/components/schemas/VerificationRequirements" }, "ttl_seconds": { "type": "integer", "minimum": 30, "maximum": 600, "default": 120 } } }, "VerificationResult": { "type": "string", "enum": [ "ALLOW", "BLOCK", "ESCALATE" ] }, "VerificationRequestStatus": { "type": "string", "enum": [ "PENDING", "DELIVERED", "PRESENTED", "APPROVED", "VERIFYING", "ALLOWED", "BLOCKED", "ESCALATED", "EXPIRED", "CANCELLED" ] }, "IntentOriginator": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "organization_name", "provenance" ], "properties": { "organization_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "organization_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "actor_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "minLength": 1, "maxLength": 120 }, "provenance": { "type": "string", "enum": [ "AUTHENTICATED_TENANT", "VERIFIED_CONNECTOR", "CALLER_DECLARED" ] } } }, "IntentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "envelope_version", "action_context", "subject_actor_id", "originator", "presentation", "verification_requirements", "issued_at", "expires_at" ], "description": "Immutable, localized context bound to one verification session.\n`subject_actor_id` always equals `action_context.actor_id`.\n", "properties": { "envelope_version": { "type": "string", "const": "presence.intent/1" }, "action_context": { "$ref": "#/components/schemas/ActionContext" }, "subject_actor_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "originator": { "$ref": "#/components/schemas/IntentOriginator" }, "presentation": { "$ref": "#/components/schemas/IntentPresentation" }, "verification_requirements": { "$ref": "#/components/schemas/VerificationRequirements" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "VerificationRequest": { "type": "object", "required": [ "request_id", "session_id", "intent_digest", "status", "envelope", "created_at", "updated_at" ], "description": "Actor-scoped projection of a durable intent-bound request. `result`\nis present exactly when the status is an outcome status (ALLOWED →\nALLOW, BLOCKED → BLOCK, ESCALATED → ESCALATE), alongside the sealed\nreceipt dossier reference.\n", "properties": { "request_id": { "type": "string", "minLength": 1 }, "session_id": { "type": "string", "minLength": 1 }, "intent_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "status": { "$ref": "#/components/schemas/VerificationRequestStatus" }, "envelope": { "$ref": "#/components/schemas/IntentEnvelope" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "result": { "$ref": "#/components/schemas/VerificationResult" }, "request_dossier_id": { "type": "string", "minLength": 1 }, "receipt_dossier_id": { "type": "string", "minLength": 1 } } }, "VerificationInvitationChannel": { "type": "string", "enum": [ "handoff", "meeting", "email", "sms", "calendar", "qr" ] }, "CreatedIntentVerification": { "allOf": [ { "$ref": "#/components/schemas/VerificationRequest" }, { "type": "object", "required": [ "session_token", "session_token_expires_in", "invitation_token", "invitation_url", "invitation_expires_at", "channel", "replayed" ], "properties": { "session_token": { "type": "string", "minLength": 1 }, "session_token_expires_in": { "type": "integer", "minimum": 1 }, "invitation_token": { "type": "string", "pattern": "^presence_it_[A-Za-z0-9_-]{32,100}$" }, "invitation_url": { "type": "string", "format": "uri", "description": "HTTPS Universal/App Link for email, SMS, calendar, chat, or QR handoff." }, "invitation_expires_at": { "type": "string", "format": "date-time" }, "channel": { "$ref": "#/components/schemas/VerificationInvitationChannel" }, "replayed": { "type": "boolean" } } } ] }, "AuthoritySelector": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "role_id" ], "properties": { "kind": { "type": "string", "const": "ROLE" }, "role_id": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{1,63}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "principal_id" ], "properties": { "kind": { "type": "string", "const": "PRINCIPAL" }, "principal_id": { "type": "string", "minLength": 1, "maxLength": 200 } } } ] }, "AuthorityRequirement": { "type": "object", "additionalProperties": false, "required": [ "requirement_version", "requirement_id", "source_decision_id", "source_dossier_id", "policy_version", "policy_reason_codes", "action_digest", "selector", "verification_requirements", "resolution", "originator", "presentation", "nonce", "issued_at", "expires_at" ], "properties": { "requirement_version": { "type": "string", "const": "decionis.authority_requirement/1" }, "requirement_id": { "type": "string", "minLength": 8, "maxLength": 200 }, "source_decision_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "source_dossier_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "policy_version": { "type": "string", "minLength": 1, "maxLength": 120 }, "policy_reason_codes": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{1,119}$" } }, "action_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "selector": { "$ref": "#/components/schemas/AuthoritySelector" }, "verification_requirements": { "$ref": "#/components/schemas/VerificationRequirements" }, "resolution": { "type": "object", "additionalProperties": false, "required": [ "quorum", "delegation", "fallback_role_ids" ], "properties": { "quorum": { "type": "integer", "const": 1 }, "delegation": { "type": "string", "enum": [ "DISALLOWED", "REQUIREMENT_REFRESH" ] }, "fallback_role_ids": { "type": "array", "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{1,63}$" } } } }, "originator": { "$ref": "#/components/schemas/IntentOriginator" }, "presentation": { "$ref": "#/components/schemas/IntentPresentation" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "CreateAuthorityRequest": { "type": "object", "additionalProperties": false, "required": [ "authority_requirement", "action_context" ], "properties": { "authority_requirement": { "$ref": "#/components/schemas/AuthorityRequirement" }, "action_context": { "$ref": "#/components/schemas/ActionContext" } } }, "AuthoritySubject": { "type": "object", "additionalProperties": false, "required": [ "actor_id", "resolution_version" ], "properties": { "actor_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "role_id": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{1,63}$" }, "resolution_version": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "AuthorityEnvelope": { "type": "object", "additionalProperties": false, "description": "The action actor remains distinct from the server-resolved authority subject.", "required": [ "envelope_version", "authority_request_id", "attempt_id", "session_id", "requirement", "requirement_digest", "action_context", "action_digest", "subject", "one_time_nonce", "issued_at", "expires_at" ], "properties": { "envelope_version": { "type": "string", "const": "presence.authority/1" }, "authority_request_id": { "type": "string" }, "attempt_id": { "type": "string" }, "session_id": { "type": "string" }, "requirement": { "$ref": "#/components/schemas/AuthorityRequirement" }, "requirement_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "action_context": { "$ref": "#/components/schemas/ActionContext" }, "action_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "subject": { "$ref": "#/components/schemas/AuthoritySubject" }, "one_time_nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "AuthorityDeliveryAttempt": { "type": "object", "additionalProperties": false, "required": [ "attempt_id", "channel", "target_device_id", "status", "attempted_at" ], "properties": { "attempt_id": { "type": "string" }, "channel": { "type": "string", "const": "MOBILE_PUSH" }, "target_device_id": { "type": "string" }, "status": { "type": "string", "enum": [ "DELIVERED", "FAILED" ] }, "attempted_at": { "type": "string", "format": "date-time" }, "reason_code": { "type": "string" } } }, "AuthorityDecision": { "type": "object", "additionalProperties": false, "required": [ "decision_version", "source_decision_id", "evaluation_id", "dossier_id", "dossier_sha256", "authority_proof_digest", "outcome", "policy_version", "reason_codes", "evaluated_at", "expires_at" ], "properties": { "decision_version": { "type": "string", "const": "decionis.authority_decision/1" }, "source_decision_id": { "type": "string" }, "evaluation_id": { "type": "string" }, "dossier_id": { "type": "string" }, "dossier_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "authority_proof_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "outcome": { "type": "string", "enum": [ "AUTHORIZED", "BLOCKED", "ESCALATE" ] }, "policy_version": { "type": "string" }, "reason_codes": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "evaluated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "AuthorityRequest": { "type": "object", "additionalProperties": false, "description": "Human APPROVED is never execution authority. A terminal release status\nis present only with a matching final Decionis decision.\n", "required": [ "authority_request_id", "attempt_id", "requirement_id", "source_decision_id", "source_dossier_id", "requirement_digest", "action_digest", "selector", "selected_actor_id", "ceremony_nonce", "envelope", "ceremony_status", "release_status", "delivery_attempts", "created_at", "updated_at", "expires_at", "request_dossier_id" ], "properties": { "authority_request_id": { "type": "string" }, "attempt_id": { "type": "string" }, "requirement_id": { "type": "string" }, "source_decision_id": { "type": "string" }, "source_dossier_id": { "type": "string" }, "requirement_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "action_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "selector": { "$ref": "#/components/schemas/AuthoritySelector" }, "selected_actor_id": { "type": "string" }, "ceremony_nonce": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Domain-separated challenge signed by the enrolled biometric authority key." }, "envelope": { "$ref": "#/components/schemas/AuthorityEnvelope" }, "ceremony_status": { "type": "string", "enum": [ "PENDING", "ROUTING", "DELIVERED", "VIEWED", "VERIFYING", "APPROVED", "DENIED", "EXPIRED", "CANCELLED", "UNDELIVERABLE" ] }, "release_status": { "type": "string", "enum": [ "NOT_READY", "PENDING", "RETRYING", "AUTHORIZED", "BLOCKED", "ESCALATED" ] }, "delivery_attempts": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/AuthorityDeliveryAttempt" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "request_dossier_id": { "type": "string" }, "proof_dossier_id": { "type": "string" }, "final_decision": { "$ref": "#/components/schemas/AuthorityDecision" } } }, "CreatedAuthorityRequest": { "allOf": [ { "$ref": "#/components/schemas/AuthorityRequest" }, { "type": "object", "required": [ "replayed" ], "properties": { "replayed": { "type": "boolean" } } } ] }, "SubmitAuthorityResponse": { "type": "object", "additionalProperties": false, "required": [ "response", "platform_assertion" ], "properties": { "response": { "type": "string", "enum": [ "APPROVE", "DENY" ] }, "platform_assertion": { "type": "string", "minLength": 32, "maxLength": 20000, "description": "JSON-encoded `presence.mobile_authority_assertion/1` containing the\nper-action authority-key signature and, when required, a platform\nintegrity token bound to the same assertion payload.\n" } } }, "DomainEventDelivery": { "type": "object", "additionalProperties": true, "required": [ "eventId", "type", "tenantId", "occurredAt", "dossierId" ], "description": "Core identity of a delivered event. The full body is shaped by the\ntenant's configured SIEM formatter, so consumers must tolerate\nadditional fields; every event points at the sealed record it refers\nto via `dossierId`.\n", "properties": { "eventId": { "type": "string" }, "type": { "type": "string", "enum": [ "verification.requested", "decision.evaluated", "escalation.opened" ] }, "tenantId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "dossierId": { "type": "string" } } } } } }