Set up Agent Identity
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 following steps are the one-time setup needed to configure Agent Identity in the Twilio Console and in your own authentication system.
You need:
- A Twilio account with Agent Identity access enabled. Access is currently invite-only and must be configured by your Twilio account representative.
- An existing authentication system that can sign JWTs and host an authentication URL.
- (Optional, but recommended) Access to your DNS provider to add a CNAME record for your custom domain.
The Twilio Console configuration page provides a temporary authentication domain you can use for testing and initial configuration. To serve the consent flow from a subdomain you control, such as auth.example.com, follow the DNS confirmation steps in the Custom Domains Console tab. You can complete this step now or return to it once the rest of the setup is working.
Your authentication system signs Trusted Auth Tokens with a private key, and Agent Identity verifies them with the matching public key.
Generate an RSA key pair for RS256 signing. For example, with OpenSSL:
1openssl genrsa -out tat-private.pem 20482openssl rsa -in tat-private.pem -pubout -out tat-public.pem
Store the private key securely in your authentication system. You upload only the public key to the Console.
Fill out the following fields in the Agent Identity configuration page in the Twilio Console:
| Field | Description |
|---|---|
| Issuer | The value your system sets as the iss claim, identifying your authentication system. For example, https://ciam.example.com. |
| Authentication URL | The URL Agent Identity redirects users to so your system can authenticate them. |
| Public keys | One or more RS256 public keys used to verify token signatures. |
The Console page also presents the following values that your system needs to complete the flow:
| Field | Description |
|---|---|
Audience (aud) | The value your tokens must set as the aud claim. This identifies your Agent Identity instance. |
| Callback URL | The URL your system posts the signed token back to after authentication. This is hosted on your custom domain, if you have one configured. |
The consent screen shows the client's name, description, and the scopes it's requesting. You can optionally customize the appearance (theme, logo, branding) and add your own Terms of Service and Privacy Policy URLs through the Consent Screen configuration page in the Twilio Console.
Register the agent or application that will request access. You provide:
- A name, description, and optional logo shown to users on the consent screen.
- One or more redirect URIs.
- The client type (first-party or third-party, confidential or public).
- The grant types the client is allowed to use.
For how client type affects consent and token behavior, see Client types and consent.
Start an authorization request, replacing YOUR_CLIENT_ID and YOUR_REDIRECT_URI with the values from the client you registered in Step 5:
1GET https://auth.example.com/oauth2/authorize2?client_id=YOUR_CLIENT_ID3&redirect_uri=YOUR_REDIRECT_URI4&response_type=code5&scope=openid%20offline_access
You should be redirected into your authentication system, returned to the consent screen, and then back to your redirect URI with an authorization code. Exchange that code at the token endpoint for an access token.
- Integrate your login system in depth: Issue Trusted Auth Tokens.
- Define what agents can request: Authorize agents with scopes and Rich Authorization Requests.
- Add human approval for sensitive actions: Require human approval with CIBA.