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.

1
2

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

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "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.

1
2
3
4

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:

1
2
3
4
5
6
7
8
9

{
  "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.

1
2
3
4
5
6
7
8
9

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:

1
2
3
4
5
6

{
  "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).

Credentials: bearer tokens and API keys#

ScaiVault accepts two credential types, and they go in different headers:

An API key sent as a bearer token is rejected — the server tries to parse it as a JWT and fails with Not enough segments. All three SDKs detect a key_ prefix and route it to the correct header automatically, so passing either as token works.

Scopes#

Scopes constrain service accounts. Human users authenticated through the admin UI bypass scope checks, on the basis that the UI login is itself the control — so adding a scope to an endpoint restricts machine callers, not people. Where that is too weak, an endpoint carries an explicit role check as well (certificate private-key export is the current example).

Wildcards work per namespace: secrets:* grants every secrets: scope, and * grants everything. A namespace wildcard does not cross namespaces — secrets:* grants no PKI access.

pki:export-key is separate from pki:write on purpose. Exporting a stored private key takes the key material outside ScaiVault's boundary, so it needs its own grant, is audited on every call, and additionally requires an administrator role for human callers.

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.

Related#

• Authentication (Getting Started)
• Multi-tenancy
• Identity Reference
• Enrollment — how a new host obtains its own credential