Claims And Scopes¶
Use this page to understand token fields and authorization strings. For the developer validation path, start with Verify Tokens.
Common Token Claims¶
| Claim | Meaning |
|---|---|
iss |
Issuer. Must match the expected SigID issuer. |
sub |
Subject identifier. Use with tenant context as the app user key. |
aud |
Audience. Must match the protected API. |
exp |
Expiration time. Reject expired tokens. |
iat |
Issued-at time. Useful for debugging and freshness. |
jti |
Token identifier. Useful for replay, audit, and revocation workflows. |
scope |
Granted scopes. Check before serving protected routes. |
tenant_id or tenant context |
Tenant/workspace context for isolation checks. |
org or organization context |
Active organization when relevant. |
amr |
Authentication methods used. |
acr |
Authentication assurance or context class. |
cnf |
Confirmation claim for sender-constrained tokens such as DPoP. |
act |
Actor claim for delegated access or token exchange. |
Claim names and exact availability depend on token type, flow, client, deployment, and configured policies.
Tenant binding is opt-in in the SDK
The token always carries tenant_id, but the SDK's tenantId validation
option is optional – when it is omitted, no tenant binding is performed
and a token from any tenant is accepted. Single-tenant resource servers
must always pass tenantId; multi-tenant ones must scope every data lookup
by the validated claims.tenantId. See
Verify Tokens.
Subject Types¶
SigID can represent multiple principal types:
| Subject type | Typical use |
|---|---|
human |
Person using an account. |
agent |
Software principal or AI agent. |
system |
Service or automation principal. |
anonymous |
Guest or trial subject where enabled. |
APIs should reject subject types that are not expected for the route.
Scope Design¶
Scopes should describe API permissions, not UI labels. Use narrow scopes that map to backend actions, such as:
| Scope pattern | Example |
|---|---|
| Read | projects:read |
| Write | projects:write |
| Admin | admin:write |
| Billing | billing:read |
| Agent tool | tools:calendar.read |
Keep scope names stable, reviewable, and least-privilege.
Delegation Claims¶
Delegated tokens may include actor information. APIs should understand whether the token represents a human directly, an agent acting for a human, or a longer delegation chain. Check both the subject and actor context before authorizing sensitive actions.
For agent-specific flows, read Agent And MCP Auth.