Auth

CortexDB authenticates every request with a PASETO v4 public token. Tokens are issued by your IdP (or a CortexDB-trusted issuer in the registry) and validated by the server — there is no /v1/auth/login endpoint.

For the full claims contract and validation order, see Authentication & Identity.

Required headers on every request

Authorization: Bearer <PASETO v4 public token>
X-Cortex-Actor:   user:alice

X-Cortex-Actor must match the token's sub claim, otherwise the server returns 401 actor_mismatch.

---

POST /v1/auth/tokens — Mint a token

Capability: auth.mint (typically granted only to server-side service accounts and the dashboard's BFF).

Short-lived PASETO v4 public tokens for M2M flows, SDK examples, and bootstrapping. Production callers should usually receive tokens from their IdP — this endpoint exists so the server can mint tokens too without a separate IdP dependency.

{
  "subject":      "user:alice",
  "ttl_seconds":  3600,
  "scopes":       ["org:acme/user:alice"]
}

| Field | Type | Notes | |---|---|---| | subject | string | Required. Sets sub on the minted token. | | ttl_seconds | int | Default 3600. Hard ceiling: tenant-configured (typ. 86400). | | scopes | string[] | Limits scopes claim on the minted token. Optional; if omitted, the token inherits the caller's scope set. |

Response

{
  "token":      "v4.public.eyJpc3MiOi...",
  "expires_at": "2026-05-15T11:42:00Z"
}

Use the returned token as Authorization: Bearer <token> on subsequent calls.

---

GET /v1/auth/whoami

Identity introspection.

Response

{
  "caller":             "user:alice",
  "tenant_id":          "acme",
  "deployment_preset":  "cloud_managed",
  "token": {
    "jti":  "j_01HX...",
    "iss":  "https://idp.acme.com/realms/main",
    "exp":  1763212929
  },
  "effective_capabilities": [
    "scope.read.local",
    "scope.read.holistic",
    "scope.write",
    "forget.cascade.derived_only",
    "diagnostics.read"
  ]
}

---

POST /v1/auth/revoke

Add a token JTI to the revocation list. Subsequent calls with that token return 401.

{
  "jti":    "j_01HX...",
  "reason": "Token leaked in support ticket #4421"
}

Returns 204. Revocation propagates across all server nodes within the configured cluster gossip interval (default 5 s).