Identity API
Identity reads accept operator-scoped authentication. Initiation, completion, delegation, provider configuration, and claim revocation are human governance actions. Agent-bearing contexts receive 403 on those routes.
Providers and sessions
- GET /v1/identity/providers - list configured provider rows.
- POST /v1/identity/verify/initiate - start a live configured provider flow.
- GET /v1/identity/verify/sessions - list pending sessions.
- POST /v1/identity/verify/sync - ask the provider for current session state.
- POST /v1/identity/verify/complete - complete by provider_key and session_ref.
- POST /v1/identity/verify/token - complete a token-based flow such as Turnstile.
A session reference does not authorize completion. Completion requires a pending, unexpired session owned by the same operator and created for the same provider. See Identity for provider status.
Claims and delegation
- GET /v1/identity/claims - list claims for the operator.
- DELETE /v1/identity/claims/:id - revoke one claim and affected Passports.
- POST /v1/identity/delegate - create a delegation claim with explicit scopes.
curl https://api.getstack.run/v1/identity/claims \
-H "Authorization: Bearer $STACK_TOKEN"Identity claims and authority proofs are separate records. Authority proof import can reference an existing operator-owned identity claim; the authority record stores the reference and hashes rather than copying the claim ciphertext. See Authority proofs.
OIDC configuration and SSO
- GET/POST /v1/identity/oidc/config - list or create an OIDC identity-provider configuration.
- PATCH/DELETE /v1/identity/oidc/config/:id - update or remove one configuration.
- POST /v1/identity/oidc/config/:id/test - test discovery and configuration.
- GET /v1/identity/sso/:slug/start and GET /v1/identity/oidc/callback - browser SSO flow.
- POST /v1/identity/sso/handoff - exchange the one-time browser handoff.
Client secrets are encrypted at rest. OIDC create, update, test, and delete reject agent-bearing contexts.
Workload issuers
SPIFFE trust-domain and WIMSE issuer CRUD lives under the Identity API. The workload uses its SVID or WIT on the separate Passport exchange route. See Workload Identity.
Service identity requirements
- GET /v1/services/:id/requirements - read this operator's policy for one service.
- POST /v1/services/:id/requirements - add one requirement.
- PUT /v1/services/:id/requirements - replace the policy or clear it with requirement: null.
- DELETE /v1/services/:id/requirements/:reqId - remove one requirement.
Requirement mutations need an admin principal and an active connection to the service. Agent-bearing contexts receive 403. A Layer 2 requirement must declare PII use and its lawful basis.
Stripe Identity webhook
POST /v1/identity/webhooks/stripe
This public route verifies the Stripe signature over the raw request body. It does not use STACK Bearer authentication.
PII policy
- PII is KMS-encrypted at rest.
- Passport JWTs do not carry raw identity attributes such as name, date of birth, address, or document number. Claim and provider metadata can still be personal data or sensitive infrastructure data.
- Initiation, explicit completion, token completion, webhook completion, delegation, revocation, and configuration mutations write audit records. Provider sync is not covered by this statement.
- Layer 2 policy writes require requires_pii: true and a non-empty lawful_basis declaration. STACK records the declaration but does not validate its legal sufficiency.
- Claim revocation is not a promise that every related audit or legal record is erased.