---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/agent-identity/api/overview#article
headline: Agent Identity API
description: Overview of Agent Identity's OAuth 2.1 and OpenID Connect endpoints and token schemas.
url: https://www.twilio.com/docs/agent-identity/api/overview
inLanguage: en
dateModified: 2026-09-18T12:02:39.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Agent Identity API

> \[!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.

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:

* [Users API](/docs/agent-identity/api/users)
* [Clients API](/docs/agent-identity/api/clients)
* [Configuration API](/docs/agent-identity/api/configuration)

> \[!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](https://datatracker.ietf.org/doc/html/rfc8414). |
| 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.

```text
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.

```text
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](/docs/agent-identity/concepts/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.

```text
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.

```text
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](https://datatracker.ietf.org/doc/html/rfc7009).

```text
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.

> \[!NOTE]
>
> 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](https://datatracker.ietf.org/doc/html/rfc9068). 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.