Skip to content
AX Framework
Trust pattern

Permission Requests

Let agents request exactly the scopes a task needs, and let people grant, inspect, and revoke them.

AX proposalTrust & Control

Problem

Agents either operate with a person's full credentials or cannot act at all. There is no middle ground that matches the task.

Context

Use this pattern when:

  • People want agents to complete tasks in your product on their behalf.
  • Different tasks need very different levels of access.

Recommended solution

Use a delegated authorization flow (for example, OAuth 2.0 with fine-grained scopes) where the agent requests specific scopes and the person approves them on a consent screen you control. Issue short-lived, scoped grants and list active grants in the person's account settings.

When an agent lacks a scope, return an error naming the scope so it can request an upgrade instead of failing opaquely.

  1. 01Define scopes around capabilities, such as orders:read or returns:create.
  2. 02Show the requested scopes in plain language on the consent screen.
  3. 03Issue short-lived, revocable grants.
  4. 04Return insufficient_scope errors that name the missing scope.

Interaction diagram

Interaction diagram for Permission Requests. 1. AI agent to Product · AX layer: request scopes: orders:read returns:create. 2. Product · AX layer to Person: Consent screen. 3. Person to Product · AX layer: Approve (24h). 4. Product · AX layer to AI agent: scoped grant.PersonAI agentProduct · AX layerrequest scopes: orders:read returns:create1Consent screen2Approve (24h)3scoped grant4
request response internal step

Example implementation

Illustrative example

Examples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.

403 insufficient_scopejson
{
  "error": {
    "code": "insufficient_scope",
    "message": "Creating a return requires the returns:create scope.",
    "requiredScopes": ["returns:create"],
    "requestUrl": "https://northwind.example/oauth/authorize?scope=returns:create"
  }
}

Accessibility and security

Accessibility

  • Consent screens must be fully keyboard and screen reader accessible; people relying on agents may be the ones who most need accessible consent.
  • Describe scopes as outcomes ("Start returns for your orders") rather than technical identifiers.

Security

  • Never ask for or accept a person's password on behalf of an agent.
  • Bind grants to a specific agent identity and audience.
  • Log grant creation, use, and revocation.

Applies the principles Clear Permissions and Human Oversight.