--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/agent-identity/concepts/how-it-works#article headline: How Agent Identity works description: Learn how Agent Identity delegates authentication to your system with Trusted Auth Tokens and issues access tokens to AI agents. url: https://www.twilio.com/docs/agent-identity/concepts/how-it-works inLanguage: en dateModified: 2026-09-18T12:02:39.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # How Agent Identity works > \[!IMPORTANT] > > 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](https://www.twilio.com/en-us/legal/service-country-specific-terms/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](/docs/agent-identity/concepts/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. 1. 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. 2. 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. 3. Agent Identity validates the TaT and starts a short-lived session for the user. 4. 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. 5. Upon user approval, Agent Identity redirects the user back to the client with a one-time authorization code. 6. 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. 7. To access data or take an action, the AI agent calls your resource server, passing the access token in the `Authorization` header. 8. Your resource server validates the token signature against the public keys at the Agent Identity JWKS endpoint, then allows the client access. > \[!NOTE] > > 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](#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](https://datatracker.ietf.org/doc/html/rfc9068)). 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](/docs/agent-identity/api/overview). ## 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. ## Client types and consent 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. ### When consent is always required Some conditions force a consent screen regardless of client type or prior consent: * The request includes `prompt=consent`. * The request includes authorization details (Rich Authorization Requests). * The `redirect_uri` uses a non-HTTPS scheme, such as a custom scheme. * The `redirect_uri` uses plain HTTP (non-HTTPS). * The `redirect_uri` uses a loopback address such as `127.0.0.1`. * A third-party client requests the `offline_access` scope.