JWT Claims Reference

AuthOS uses JSON Web Tokens (JWT) for authentication. This reference documents all JWT claims and token types.

Token Types

Token Type	Purpose	Lifetime	Claims / Context
Access Token	API authentication	24 hours	Standard claims
Refresh Token	Token renewal	30 days	Opaque UUID
Pre-auth Token	MFA pending	5 minutes	`mfa_required: true`
Impersonation	Debugging	15 minutes	`act` claim present

Claims Structure

Standard access tokens contain these claims:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "exp": 1705401600,
  "iat": 1705315200,
  "jti": "unique-token-id",
  "org": "acme-corp",
  "service": "main-app",
  "is_platform_owner": false,
  "mfa_required": null,
  "mfa_verified": null,
  "saml_state": null,
  "act": null
}

Claim Details

Claim	Type	Required	Description
`sub`	`string`	Yes	Subject - User ID (UUID)
`email`	`string`	Yes	User’s email address
`exp`	`integer`	Yes	Expiration time (Unix timestamp)
`iat`	`integer`	Yes	Issued at time (Unix timestamp)
`jti`	`string`	Yes	JWT ID - Unique token identifier
`org`	`string`	No	Organization slug
`service`	`string`	No	Service slug
`is_platform_owner`	`boolean`	No	True if user is a platform owner
`mfa_required`	`boolean`	No	True for pre-auth tokens requiring MFA
`mfa_verified`	`boolean`	No	True if MFA was successfully verified
`saml_state`	`string`	No	Internal state for SAML flows
`act`	`object`	No	Actor claim for impersonation (RFC 8693)

Impersonation (Actor Claim)

When a platform administrator impersonates a user, the token includes an act (actor) claim:

{
  "sub": "target-user-uuid",
  "act": {
    "sub": "admin-user-uuid"
  }
}

This ensures that all actions performed during the impersonation session are correctly audited to both the target user and the actual administrator.

Token Contexts

Platform Context Token

Used for platform-wide administration.

org: null
service: null
is_platform_owner: true

Organization Context Token

Used for organization-level administration.

org: "acme-corp"
service: null

Service Context Token

Standard end-user token for a specific application.

org: "acme-corp"
service: "main-app"

Token Validation

JWKS Endpoint

Retrieve public keys for token verification:

GET /.well-known/jwks.json

Response:

{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "kid": "dev-key-1",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Validation Steps

Verify Signature - Use public key from JWKS matching the kid in the JWT header.
Check Expiration - Ensure exp > current time.
Check NBF - Ensure current time >= nbf (if present).
Validate Context - Check org and service claims against your application’s requirements.
Audit Check - Optionally check jti against a revocation list/database.