---
title: Authentication
path: reference/authentication
status: published
---

# Authentication Reference

Token exchange, introspection, and identity lookup. For conceptual overview see [Authentication](../getting-started/authentication).

ScaiVault delegates identity to [ScaiKey](https://scaikey.scailabs.ai). 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](https://scaikey.scailabs.ai). ScaiVault accepts the resulting bearer tokens on every endpoint.

## Related

- [Authentication (Getting Started)](../getting-started/authentication)
- [Multi-tenancy](../core-concepts/multi-tenancy)
- [Identity Reference](./identity)