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.
- 01Define scopes around capabilities, such as orders:read or returns:create.
- 02Show the requested scopes in plain language on the consent screen.
- 03Issue short-lived, revocable grants.
- 04Return insufficient_scope errors that name the missing scope.
Interaction diagram
Example implementation
Illustrative exampleExamples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.
{
"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.
Related patterns
Applies the principles Clear Permissions and Human Oversight.