Agent Identity API

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

This page lists the OAuth 2.1 and OpenID Connect protocol endpoints Agent Identity exposes at your custom domain (shown here as https://auth.example.com), and the token schema's Agent Identity issues. Discovery, JWKS, token, and UserInfo endpoints follow their respective specifications.

For managing users, clients, and authorization configuration, see:

(warning)

Warning

Endpoint paths and schemas are subject to change before General Availability.

Discovery endpoints

Endpoint	Method and path	Purpose
Authorization server metadata	`GET /.well-known/oauth-authorization-server`	Advertises endpoint locations and capabilities per RFC 8414.
OpenID Connect discovery	`GET /.well-known/openid-configuration`	The OpenID Connect form of the metadata document.
JWKS	`GET /.well-known/jwks.json`	The public keys your resource servers use to validate token signatures.

Authorization endpoint

Start an authorization code flow. A browser user agent must load this URL.

GET https://auth.example.com/oauth2/authorize

Parameter	Required	Notes
`client_id`	Required	The client requesting authorization.
`redirect_uri`	Required	Must match a redirect URI registered for the client. May be omitted if the client has exactly one registered redirect URI.
`response_type`	Required	Must be `code`.
`scope`	Optional	A space-delimited list of scopes. Defaults to `openid` if omitted.
`state`	Optional	An opaque value returned to the client unchanged.
`nonce`	Optional	A value that binds a client session to the ID token.
`code_challenge`	Optional	The PKCE challenge. Required for some redirect URI types.
`authorization_details`	Optional	A JSON-encoded array of Rich Authorization Request objects.

Responses

If the user isn't authenticated, Agent Identity returns a 302 redirect into the Trusted Auth Token flow.
If the user is authenticated and consent is required, Agent Identity returns a 200 with an HTML consent form.
If the user is authenticated and consent isn't required, Agent Identity returns a 302 redirect to the client's redirect URI with an authorization code.

Token endpoint

Exchange an authorization code, refresh token, client credentials, or CIBA request for tokens.

POST https://auth.example.com/oauth2/token

Supported grant types:

authorization_code: exchange a one-time authorization code for tokens.
client_credentials: obtain a token for machine-to-machine use. Available to confidential clients only (both first-party and third-party).
refresh_token: exchange a refresh token for a new access token.
urn:openid:params:grant-type:ciba: poll for the result of a CIBA approval request. See Require human approval with CIBA.

A successful response returns an access_token, a token_type of Bearer, an expires_in value in seconds, and, where applicable, an id_token and a refresh_token.

Backchannel authentication endpoint

Start a CIBA approval request.

POST https://auth.example.com/oauth2/backchannel/authorize

UserInfo endpoint

Return claims about the authenticated user. Authenticate with the access token in the Authorization header.

GET https://auth.example.com/oauth2/userinfo

The claims returned depend on the scopes in the access token, following the OpenID Connect scope-to-claim mapping. For example, a phone scope returns phone_number and phone_number_verified.

Token revocation endpoint

Revoke a refresh token per RFC 7009.

POST https://auth.example.com/oauth2/revoke

Send the token and an optional token_type_hint of refresh_token. Agent Identity returns 200 OK for a valid, expired, or malformed token.

(information)

Info

Access tokens can't be revoked because they're stateless. A request to revoke an access token returns an unsupported_token_type error.

Token schemas

Access token

An access token is a JWT following RFC 9068. It carries the standard iss, aud, sub, client_id, iat, exp, and jti claims, plus any access token claims you set for the user through the Trusted Auth Token.

ID token

An ID token follows the OpenID Connect Core format. Agent Identity returns it to clients granted the openid scope. It carries the standard iss, aud, sub, iat, exp, and jti claims, an optional nonce, and any ID token claims you set for the user.

Refresh token

A refresh token is an opaque string returned when a client requests the offline_access scope. Refresh token behavior depends on the client type:

Public clients: refresh tokens rotate on each use. Agent Identity detects reuse of a previously used refresh token and revokes the token chain and the underlying grant.
Confidential clients: refresh tokens don't rotate. Presenting a valid refresh token returns a new access token and extends the refresh token's idle timeout.