Authorize agents with scopes and Rich Authorization Requests

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.

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.

1
{
2
  "scope_definitions": [
3
    {
4
      "name": "orders:read",
5
      "description": "View your order history and order details",
6
      "contains": []
7
    },
8
    {
9
      "name": "orders:admin",
10
      "description": "Manage and modify all your orders",
11
      "contains": ["orders:read"]
12
    },
13
    {
14
      "name": "payments:charge",
15
      "description": "Charge your saved payment methods",
16
      "contains": []
17
    }
18
  ]
19
}

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.

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.

Before an agent can use a RAR type, you must configure it via the Configuration API (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.

1
{
2
  "authorization_details_definitions": [
3
    {
4
      "type": "purchase",
5
      "schema": { "...": "..." },
6
      "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.",
7
      "approval_ttl_seconds": 600,
8
      "approval_methods": ["WEB", "RCS"]
9
    }
10
  ]
11
}

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.

An agent submits a payload that matches a registered type:

1
{
2
  "authorization_details": [
3
    {
4
      "type": "purchase",
5
      "item": "Trail Running Shoes",
6
      "price": 129.99,
7
      "currency": "USD",
8
      "merchant": "Example Outfitters",
9
      "quantity": 1,
10
      "sku": "TRS-BLK-11",
11
      "shipping_address": "123 Main St, San Francisco, CA"
12
    }
13
  ]
14
}

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.

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.