Issue Trusted Auth Tokens

(new)

Private Beta

Agent Identity is available as a Private Beta product, and the information contained in this document is subject to change. You acknowledge and agree that your use of Agent Identity is subject to the terms of the Services in Private Beta. Some features are not yet implemented and others may change before the product is declared as Generally Available. Private Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

The Trusted Auth Token (TaT) flow is how Agent Identity delegates user authentication back to your existing system. Your system authenticates the user, signs a short-lived JWT that describes them, and posts it back to Agent Identity. Agent Identity validates the token, starts a session, and continues the OAuth flow.

The Trusted Auth Token flow

A user tries to complete an action that needs authentication, usually an OAuth authorization request. Agent Identity redirects the user into the TaT flow.
Agent Identity generates a one-time nonce, stores it in a cookie on the user's device, and redirects the user to your Authentication URL with the nonce as a query parameter.
Your system authenticates the user with whatever mechanism you use today.
Your system signs a Trusted Auth Token that includes the required claims, including the nonce.
Your system redirects the user back to the Agent Identity callback URL using a form post, with the token in the request body.
Agent Identity validates the token, issues a short-lived session cookie, and returns the user to the flow they started.

Trusted Auth Token schema

Claims

The following claims are required:

Claim	Type	Description
`iss`	string	Must match the Issuer you set in the Console.
`aud`	string	Must match the Audience shown in the Console. Must be a string value.
`sub`	string	A unique, stable identifier for the user in your system.
`exp`	number	Expiration time, in Unix seconds.
`iat`	number	Issued-at time, in Unix seconds.
`nonce`	string	The value Agent Identity passed to your Authentication URL.

Beyond these required claims, the following user data claims are optional. In the JWT, prefix each optional claim name with https://ciam.twilio.com/ (for example, https://ciam.twilio.com/scopes). See the sample token below.

Claim	Type	Description
`user_display_name`	string	A human-readable display name for the user, shown on the consent screen.
`scopes`	string	A space-delimited list of scopes this user is allowed to grant. A user can grant a client only the scopes present here. If omitted, the user can only grant the built-in OIDC scopes.
`authorization_details_types`	string	A space-delimited list of Rich Authorization Request types this user may grant.
`access_token_claims`	object	The custom claims added to every access token issued for this user.
`id_token_claims`	object	The custom claims added to every ID token issued for this user.
`userinfo_claims`	object	The custom claims returned from the UserInfo endpoint for this user.

(information)

Info

Reserved claims (sub, iss, aud, exp, iat, nbf, jti, and other standard OIDC claims) are set automatically by Agent Identity and can't be overridden. If you include a reserved claim name in your custom data, the system-assigned value takes precedence and your value is ignored.

Sample token

Sign the token with RS256.

Header

1{
2  "alg": "RS256"
3}

Body

1{
2  "iss": "https://ciam.example.com",
3  "aud": "https://auth.example.com",
4  "sub": "USER_12345",
5  "exp": 1735689600,
6  "iat": 1735689300,
7  "nonce": "NONCE_FROM_QUERY_PARAM",
8
9  "https://ciam.twilio.com/user_display_name": "Jo Smith",
10  "https://ciam.twilio.com/scopes": "openid offline_access orders:read",
11  "https://ciam.twilio.com/authorization_details_types": "purchase refund",
12
13  "https://ciam.twilio.com/access_token_claims": {
14    "email": "jo@example.com"
15  },
16  "https://ciam.twilio.com/id_token_claims": {
17    "email": "jo@example.com"
18  },
19  "https://ciam.twilio.com/userinfo_claims": {
20    "https://example.com/claims/tier": "gold"
21  }
22}

How Agent Identity validates the token

Agent Identity accepts the token only when all of the following hold:

The iss claim matches your configured Issuer.
The aud claim matches your instance's Audience.
The exp claim is in the future (the token hasn't expired).
The nonce matches the value stored in the user's cookie and hasn't been used before.

When validation succeeds, Agent Identity extracts the user's sub and other claims and stores them on the user record. A later sign-in that carries new values (for example, an updated email) updates the stored record.