Skip to main content

Session Tokens

Mint short-lived, downscoped tokens for browser and mobile clients. Never expose your API key to a frontend.

What it is​

A session token is a time-limited bearer token with a subset of your API key's permissions. Your backend mints one, hands it to the client, and the client uses it for direct API calls. The token expires in minutes — a leaked token is useless quickly.

How it works​

Minting a token​

cURL

curl -X POST https://api.wardenauthz.com/v1/session-token/mint \
  -H "x-api-key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopeId": "workspace-eng",
    "permissionIds": ["documents:read", "reports:read"],
    "ttlSeconds": 600
  }'
{
  "token": "st1.eyJzdWIiOi...2FjMjA4M2U",
  "expiresAt": "2026-07-15T12:10:00Z"
}

Downscoping​

Pass a subset of your API key's permissions. If your key can read and write documents and manage billing, but the client only needs to read documents, pass only ["documents:read"]. The token can't do anything else — even if stolen.

Revocation​

curl -X POST https://api.wardenauthz.com/v1/session-token/revoke \
  -H "x-api-key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "token": "st1.eyJzdWIi..." }'

Revoke a token before it expires. Use this on logout.

Prerequisites​

  • session-token:create on your management key.
  • Only API keys can mint tokens — Cognito users cannot.

Edge cases​

  • TTL maximum is 900 seconds (15 minutes). Tokens above 900s are rejected.
  • Expired tokens return 401. The authorizer checks the TTL on every call.
  • Tampered tokens return 401. Tokens are HMAC-signed — modifying the payload invalidates the signature.