/v1/auth

curl -X POST "https://example.com/v1/auth/signup" \  -H "Content-Type: application/json" \  -d '{}'

{  "token": "string",  "jti": "string",  "expires_at": "2019-08-24T14:15:22Z",  "user_id": "string",  "scope": "string",  "tier": "string"}

curl -X POST "https://example.com/v1/auth/tokens" \  -H "Content-Type: application/json" \  -d '{    "subject": "string"  }'

{  "token": "string",  "jti": "string",  "expires_at": "2019-08-24T14:15:22Z"}

curl -X GET "https://example.com/v1/auth/whoami"

{  "caller": "string",  "tenant_id": "string",  "deployment_preset": "string",  "token": {    "jti": "string",    "iss": "string",    "exp": 0  },  "effective_capabilities": [    "string"  ]}

curl -X POST "https://example.com/v1/auth/revoke" \  -H "Content-Type: application/json" \  -d '{    "jti": "string"  }'

CortexDB uses PASETO v4 public tokens. Every authenticated request carries Authorization: Bearer <token> and X-Cortex-Actor (which must match the token's sub).

Endpoints

• POST /v1/auth/signup {} — anonymous free-tier token (7-day TTL). Returns { token, jti, user_id, scope, tier, expires_at } (jti is what /v1/auth/revoke takes). A server with CORTEX_DISABLE_ANON_SIGNUP=1 answers 404 (v0.12.6+); CortexDB Cloud does, since its accounts sign up at cortexdb.ai and create tokens on the dashboard.
• POST /v1/auth/tokens — mint a service-account token (requires the auth.mint capability; ttl_seconds is clamped to a 60 s minimum; a 7-day TTL is honoured). Body: { subject, scope?, ttl_seconds?, caps?, scopes? }.
  • scope only says where your auth.mint is checked (omit it for a deployment-wide check). It does not confine the minted token.
  • caps narrows the token's capabilities; capabilities is still accepted as an alias.
  • scopes confines capabilities to subtrees, each entry <capability>:<scope-path>[/*], for example scope.read:org:acme/team:b/*. Entries are validated at mint: a bare path is 422 INVALID_BODY.
  • The CLI sends scopes with cortexdb auth tokens --confine CAP:PREFIX; its --scope is the check location.
  • tenant (v0.12.6+, hosted with CORTEX_V1_TENANT_AUDIENCES=1 only) names the billing tenant the token belongs to, for example acct_45: its audience becomes cortexdb:tenant:acct_45, so it reaches org:acct_45/... and never another tenant's records. It needs a deployment-wide mint (no scope) by a credential of the deployment's own audience, and every scopes entry (at least one) must lie in org:<tenant>; otherwise 422 INVALID_BODY. A tenant's own token never mints. This is how CortexDB Cloud issues each account's tokens; on a self-hosted server leave it out.
• GET /v1/auth/whoami → { caller, tenant_id, deployment_preset, token: { jti, iss, exp }, effective_capabilities }.
• POST /v1/auth/revoke { jti, reason } → 204.