How Agent Identity works

(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.

Agent Identity acts as an OAuth 2.1 and OpenID Connect authorization server for your application. This page explains the actors involved, how authentication is delegated back to your system, and how tokens flow through the system.

Key concepts

Resource owner: the end user who owns the data and grants access to it.
Client: the application requesting access on the user's behalf, such as an AI agent or an MCP server.
Authorization server: the Twilio Agent Identity service. It authenticates the user through your system, records their consent, and issues tokens to the client.
Resource server: your platform, with its existing auth system. It validates the access token and returns protected data if the token is valid and carries the required permissions.
Trusted Auth Token (TaT): a JWT your existing system signs to tell Agent Identity who the user is and what they're allowed to grant. This is how authentication is delegated back to you.

User authentication is delegated to your platform

Agent Identity doesn't manage your users' credentials or sessions. Your authentication system stays in control and interfaces with Agent Identity using Trusted Auth Tokens.

The TaT flow is a lightweight single sign-on (SSO) profile. Your system authenticates the user however it does today, then signs a short-lived JWT (the Trusted Auth Token) that contains context on who the user is and what scopes they can delegate to an agent. The user's browser delivers that token to Agent Identity through a form-post redirect.

Because authentication is delegated this way, you keep full control of the login experience and Twilio's authorization servers don't receive sensitive information like passwords.

For the token schema and step-by-step flow, see Issue Trusted Auth Tokens.

The authorization flow

The following sequence describes a complete OAuth authorization code grant, which is the primary flow for agents acting on a user's behalf.

The client (for example, an AI agent) redirects the user to the Agent Identity authorization endpoint with its client_id, a redirect_uri, response_type=code, and the scopes it wants.
If the user isn't authenticated, Agent Identity redirects them to the Trusted Auth Token flow. Your system authenticates the user and returns a signed TaT.
Agent Identity validates the TaT and starts a short-lived session for the user.
If the request needs consent (required for third-party clients; first-party clients skip consent unless specific conditions apply), Agent Identity serves a hosted consent screen that lists the requested permissions and basic information about the client.
Upon user approval, Agent Identity redirects the user back to the client with a one-time authorization code.
The client exchanges the authorization code for an access token at the token endpoint. It can also receive an ID token and, if it requested the offline_access scope, a refresh token.
To access data or take an action, the AI agent calls your resource server, passing the access token in the Authorization header.
Your resource server validates the token signature against the public keys at the Agent Identity JWKS endpoint, then allows the client access.

(information)

Info

First-party clients that you own are trusted by default and skip the consent screen. Third-party clients always require consent. For the full rules, see Client types and consent.

Tokens Agent Identity issues

Agent Identity issues three kinds of tokens. All are configurable for lifetime in the Console.

Access token: a JWT following the JWT Profile for OAuth 2.1 Access Tokens (RFC 9068). Your resource server validates it locally using the published public keys. Access tokens are stateless, so they can't be revoked before they expire. Keep their lifetime short.
ID token: a JWT following the OpenID Connect Core ID Token format. Agent Identity returns an ID token to any client granted the built-in openid scope.
Refresh token: an opaque string returned when a client requests the built-in offline_access scope. A client exchanges a refresh token for a new access token. Refresh tokens can be revoked.

For token schemas and endpoint details, see the Agent Identity API.

Your custom domain

Agent Identity runs on a subdomain that you control, such as auth.example.com, configured with a DNS CNAME record. Serving the flow from your own domain improves security and gives users a consistent, branded experience. You configure this domain in the Twilio Console.

Every client has two properties that determine how it behaves.

Ownership: first-party clients are ones you own and are trusted by default. Third-party clients are built by others and always require user consent.
Confidentiality: confidential clients can store a secret. Public clients can't.

Combining these gives four client types.

Client type	Consent	Secret	Notes
First-party confidential	Not required by default	Yes	Trusted; can also use the client credentials grant.
First-party public	Not required by default	No	Must use PKCE.
Third-party confidential	Required	Yes	External server-based app.
Third-party public	Required	No	External native or CLI app; must use PKCE; refresh tokens rotate.

After a user consents to a third-party client, later flows skip the consent screen unless the requested scopes exceed the existing grant or one of the always-require-consent conditions fires.