Authentication

Token exchange, introspection, and identity lookup. For conceptual overview see Authentication.

ScaiVault delegates identity to ScaiKey. Most auth endpoints live on ScaiKey; ScaiVault exposes a thin layer for token introspection and context discovery.

Base path: /v1/auth/

GET /v1/auth/whoami#

Identify the caller from the bearer token. Useful for debugging — shows you who ScaiVault sees you as.

bash
curl -H "Authorization: Bearer $TOKEN" \
     https://scaivault.scailabs.ai/v1/auth/whoami

Response:

json
{
  "identity_id": "user:alice@acme.example",
  "identity_type": "user",
  "display_name": "Alice Smith",
  "tenant_id": "tnt_acme_prod",
  "partner_id": "ptn_acme",
  "scopes": ["secrets:read", "secrets:write", "audit:read"],
  "groups": ["group:sre", "group:oncall"],
  "roles": ["tenant_admin"],
  "mfa_verified_at": "2026-04-23T13:45:00Z",
  "token_expires_at": "2026-04-23T14:45:00Z"
}

Required: authenticated.

POST /v1/auth/introspect#

Validate a token without using it. Common in gateway/proxy scenarios.

bash
curl -X POST https://scaivault.scailabs.ai/v1/auth/introspect \
  -H "Authorization: Bearer $SELF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token": "token-to-introspect"}'

Response:

json
{
  "active": true,
  "identity_id": "sa:reporting-service",
  "identity_type": "service_account",
  "tenant_id": "tnt_acme_prod",
  "scopes": ["secrets:read"],
  "expires_at": "2026-04-23T15:00:00Z",
  "issued_at": "2026-04-23T14:00:00Z"
}

If the token is invalid or expired: {"active": false} with HTTP 200.

Required: admin scope.

POST /v1/auth/exchange#

Exchange a foreign token (workload identity from Kubernetes, AWS, GCP, etc.) for a ScaiKey-minted ScaiVault token. Used by services that don't have static credentials.

bash
curl -X POST https://scaivault.scailabs.ai/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "token_exchange",
    "subject_token": "<k8s service account JWT>",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "audience": "scaivault",
    "resource": "https://scaivault.scailabs.ai"
  }'

Response:

json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "secrets:read"
}

Configure the trust relationship (which foreign issuers to accept, how to map to ScaiKey identities) in the admin UI under Access → Token Exchange.

Required: none (the subject token authenticates).

OAuth flows on ScaiKey#

Everything else — authorization code + PKCE, client credentials, refresh token rotation — happens on ScaiKey directly. See scaikey.scailabs.ai/docs. ScaiVault accepts the resulting bearer tokens on every endpoint.

Authentication

GET /v1/auth/whoami#

POST /v1/auth/introspect#

POST /v1/auth/exchange#

OAuth flows on ScaiKey#

Related#