Tokens and claims

Look up each token a project issues, its lifetime, signing algorithm and claims, and how to validate one.

A project issues several kinds of token. Each is signed with one of the project's keys, published at https://acme.authfi.io/.well-known/jwks.json.

Token types

A claim is a named value inside a token. A JWT is a signed token whose claims any holder can read and any service can verify.

The ID token has the same lifetime as the access token.

ID token

Tells an application who signed in. It is returned by the token endpoint when the scope includes openid. See Add sign-in to an app.

{
  "iss": "https://acme.authfi.io",
  "sub": "[email protected]",
  "aud": "<your client ID>",
  "email": "[email protected]",
  "email_verified": true,
  "name": "Ada Lovelace",
  "groups": ["engineering"],
  "roles": ["developer"],
  "auth_time": 1760000000,
  "iat": 1760000000,
  "exp": 1760000900
}

The ID token carries email, email_verified, name, groups and roles whatever scopes you request. Scopes decide what userinfo returns. See Scopes.

groups lists only the groups assigned to the application or shared with it, not every group the person belongs to. See Application types.

Access token

Lets an application or a service call an API. It follows the JWT access token profile (RFC 9068). See Sessions and Service to service.

sid, amr and acr describe a person's sign-in. A service's token has none of them, because nobody signed in.

An access token carries no name or email. Read those from the ID token or from userinfo.

acr and amr values

acr is the sign-in strength reached. An application asks for one with acr_values at the authorization endpoint. Several values, separated by spaces, mean any of these, or stronger. See Sessions.

amr is the list of methods the person used.

Custom claims

A claim that a webhook action returns is added to the token under custom. See Actions at sign-in.

{ "sub": "[email protected]", "custom": { "plan": "enterprise", "cost_center": "R-204" } }

Refresh token

Gets new tokens without another sign-in, at the token endpoint. It is not a JWT. See Refresh tokens.

Agent access token

Lets an AI agent call a service. It is returned by the agent token endpoint, /apis/regional/v1/ai/auth/token, and follows RFC 9068. An agent has no refresh token: when the access token expires, it signs a new client assertion. See Give an AI agent an identity and Accept agents at your own API.

capabilities holds names only. AuthFI keeps the limits on each capability and checks them when the agent acts. See Limit what an agent may do.

A token requested with no resource is issued for the project's MCP gateway.

act tells the two cases apart.

In a token issued after a person approves through CIBA, scope is what the person approved, and exp is 15 minutes after issue.

Transaction token

Binds an agent to one action and its details. The agent exchanges its access token for one before a sensitive action. See Ask before a sensitive action.

{
  "typ": "txn_token+jwt",
  "sub": "agt_7f3a9c21",
  "txn": "0b7d6a52-…",
  "azd": {
    "action": "transfer:accounts",
    "resource": "account:4821",
    "context": { "amount": 1200, "currency": "USD", "account_type": "business" }
  }
}

Client assertion

Proves an agent's identity at the agent token endpoint. The agent creates and signs it with its own private key. This is private_key_jwt (RFC 7523). See Give an AI agent an identity.

An assertion is accepted once. Build a new one for every request.

Other signed tokens

A project signs these tokens for one purpose each. The page that uses each token lists its claims.

Checking a token

A service validates a JWT itself, without a call to AuthFI. Most JWT libraries make these checks when you configure them with the issuer, the keys URL, the audience and the algorithm.

1. Verify the signature with the key whose kid matches the token's header.
2. Check that iss is the issuer of the project you trust.
3. Check that aud names this service. Reject a token issued for another service.
4. Check that exp is in the future.
5. For a bearer token, check that the header typ is at+jwt. An ID token has typ: JWT and is not a bearer credential.

For a transaction token, also compare azd with the request in front of you, and reject any difference. See Accept agents at your own API.

Keys. Find the key by kid. Cache the key set, and fetch it again when you meet a kid you do not know. See Keys and secrets.

Revocation. A signature check accepts a token until it expires. To learn sooner that an agent was revoked, subscribe to revocation events. An application with a secret can also ask the introspection endpoint.

Sign-in strength. Before a sensitive action, read acr from the token and deny the action if it is weaker than you need.