--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/agent-identity/concepts/scopes-and-rar#article headline: Authorize agents with scopes and Rich Authorization Requests description: Define what AI agents can do with OAuth scopes and Rich Authorization Requests (RAR) for structured, one-off actions. url: https://www.twilio.com/docs/agent-identity/concepts/scopes-and-rar inLanguage: en dateModified: 2026-09-18T12:02:39.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Authorize agents with scopes and Rich Authorization Requests > \[!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 represents what an agent is allowed to do with two primitives: OAuth scopes for coarse-grained, standing permissions, and Rich Authorization Requests (RAR) for structured, one-off actions. > \[!NOTE] > > Agent Identity is a representation and approval layer, not an enforcement > engine. Your resource servers and gateways stay responsible for enforcing the > permissions carried in a token. This also offers the flexibility to map > permissions into your existing authorization model. ## OAuth scopes Scopes are opaque strings that represent standing capabilities. Most API gateways and service meshes can authorize requests based on the `scope` claim in a JWT, so scopes are a portable way to enforce access with tools you likely already run. Agent Identity supports the built-in OpenID Connect scopes (`openid`, `email`, `profile`, `phone`, and `offline_access`) and custom scopes you define. ### Define a custom scope Register your scopes with Agent Identity and give each one display metadata. We recommend following a `resource:action` naming convention, such as `orders:read` or `payments:charge`. ```json { "scope_definitions": [ { "name": "orders:read", "description": "View your order history and order details", "contains": [] }, { "name": "orders:admin", "description": "Manage and modify all your orders", "contains": ["orders:read"] }, { "name": "payments:charge", "description": "Charge your saved payment methods", "contains": [] } ] } ``` Each definition has three required fields: * **`name`**: the scope string used in OAuth requests and tokens. * **`description`**: human-readable text shown to users on the consent screen. * **`contains`**: a list of scopes this scope implies. Use an empty array if this scope doesn't contain others. The `contains` field defines a hierarchy between scopes. Agent Identity uses this hierarchy to validate scope configurations and to simplify the consent screen. For example, a request for `orders:admin` and `orders:read` shows the user a single line, "Manage and modify all your orders," rather than two overlapping permissions. ## Rich Authorization Requests Some actions can't be captured as a standing scope. Charging a specific amount to a specific merchant is a one-time, parameterized action. For these cases, Agent Identity supports Rich Authorization Requests, where the agent submits a structured JSON payload describing the action it wants to take. RAR is especially useful with human-in-the-loop approvals, because it lets you show a user the exact details of what they're approving. See [Require human approval with CIBA](/docs/agent-identity/concepts/ciba). ### Register an authorization detail type Before an agent can use a RAR type, you must configure it via the [Configuration API](/docs/agent-identity/api/configuration) (`PATCH /v1/Configuration/Authorization`). Each type needs a JSON schema, a text rendering template, an optional TTL that constrains the lifetime of any access token issued for it, and the approval methods it supports. ```json { "authorization_details_definitions": [ { "type": "purchase", "schema": { "...": "..." }, "template": "Purchase Request\nAn agent is requesting approval to make a purchase.\n\nItem: {{item}}\nMerchant: {{merchant}}\nPrice: {{price}} {{currency}}\nQuantity: {{quantity}}\n\nIf approved, the purchase will be completed immediately.\nApprove or deny this request.", "approval_ttl_seconds": 600, "approval_methods": ["WEB", "RCS"] } ] } ``` Keep rendering templates text-only so they work across channels, including SMS and RCS. The `approval_methods` field specifies how the request can be approved: `WEB` (a hosted approval screen) or `RCS` (an in-channel quick-reply action). At least one method is required. When the approval TTL is shorter than the default access token lifetime, the approval TTL caps the access token's lifetime. This means access tokens for time-sensitive actions like purchases expire sooner than tokens carrying only scopes. ### Submit a Rich Authorization Request An agent submits a payload that matches a registered type: ```json { "authorization_details": [ { "type": "purchase", "item": "Trail Running Shoes", "price": 129.99, "currency": "USD", "merchant": "Example Outfitters", "quantity": 1, "sku": "TRS-BLK-11", "shipping_address": "123 Main St, San Francisco, CA" } ] } ``` Agent Identity validates the payload against the registered schema, renders it with the template, and presents it to the user for approval—either in the browser or through a backchannel approval flow. On approval, the authorization detail is added as a claim to the access token issued to the agent. Your resource server reads that claim when it processes the request. ## Permission limits Agent Identity applies two layers of allowlists so a request can't exceed what either the user or the client is permitted to do. * **User allowlists**: the scopes and authorization detail types a user may grant, passed in the user's Trusted Auth Token claims. At request time, Agent Identity filters out any scopes or types the user isn't allowed to grant. * **Client allowlists**: the maximum scopes and authorization detail types a client may request, set when you register the client. At request time, Agent Identity filters out any scopes or types that exceed the client's allowlist.