OAuth Rich Authorization Requests (RAR) Guide: Fine-Grained Consent for APIs and Agents

OAuth scopes are too coarse to say "this agent may pay 50 euros to this payee, once" or "read these two accounts until Friday". OAuth 2.0 Rich Authorization Requests (RAR), published by the IETF as RFC 9396 in May 2023, adds an authorization_details parameter that carries structured, typed permission objects through the whole OAuth flow, from the request to the consent screen, the token and the API. It is the mechanism behind open banking payment consents, OpenID for Verifiable Credential Issuance and, increasingly, transaction level approval for AI agents. This guide explains how RAR works, where it fits beside scopes, resource indicators, PAR and CIBA, and the design mistakes that undo its value. It is for API designers, identity architects and teams granting agents access to real systems.

Key takeaways

• RAR expresses what scopes cannot. Each entry in authorization_details is a JSON object with a mandatory type and API defined fields such as amounts, accounts, locations and actions.
• It travels end to end. The same structure appears in authorisation, device and CIBA requests, token requests and responses, JWT access tokens and introspection responses.
• Integrity is not optional. Because details pass through the browser, the RFC requires protection with signed request objects or Pushed Authorization Requests (PAR).
• The type definition is the security design. Each type must define its fields, how a request compares with a previous grant and whether the server may enrich it.
• For agents, RAR turns consent into a transaction. A human approves a specific action and the resulting token carries only that, which limits what a hijacked agent or stolen token can do.

What it is

RFC 9396 (Standards Track, authors Lodderstedt, Richer and Campbell) defines the authorization_details request parameter for carrying fine-grained authorisation data that scope cannot express. Its value is a JSON array of objects. Every object must contain a type string, which identifies the kind of authorisation and decides which other fields are allowed. Several entries, including several of the same type, can appear in one request.

The RFC defines five common data fields that any type may reuse, all optional:

Types then add their own fields. The RFC's examples include payment_initiation (instructed amount, creditor name and account) and account_information, and its appendix sketches OpenID Connect claims, electronic signing, tax data and eHealth. Real deployments now depend on it: OpenID for Verifiable Credential Issuance 1.0 (Final, September 2025) requires authorization_details with type openid_credential and a credential_configuration_id, and returns credential_identifiers in the token response.

RAR sits on the core OAuth flows rather than replacing them. See the OAuth 2.0 and OpenID Connect Guide for the roles and grants it extends.

How it works

1. Discovery: the authorisation server (AS) lists the types it understands in authorization_details_types_supported. Clients can declare the types they use with the authorization_details_types registration parameter.
2. Request: the client sends authorization_details in the authorisation request (RFC 6749), the device authorisation request (RFC 8628) or the CIBA backchannel request. For anything large or sensitive the RFC recommends pushing it with PAR (RFC 9126) or wrapping it in a signed request object (RFC 9101).
3. Validation: the AS must reject unknown types and malformed objects with the error invalid_authorization_details, and must sanitise values before showing them, because consent screens can be abused to display attacker supplied text.
4. Consent: the user sees the merged requirements of any scope and authorization_details values. They may grant a subset, and the AS may enrich a type where its definition allows, for example by adding the accounts the user picked.
5. Token response: the AS returns the authorization_details actually granted. Clients must expect them to differ from the request.
6. Token request narrowing: a client may send authorization_details on a token request to ask for a token covering less than the grant, for example one account per API call. Asking for more than the grant allows returns invalid_authorization_details.
7. Enforcement: for JWT access tokens the RFC recommends an authorization_details top-level claim, filtered to the audience; for opaque tokens the introspection response carries it. The resource server checks the request against these details, not just the scope.

A worked agent example

An AI shopping agent needs to pay a supplier. Rather than holding a standing payments scope, it sends a CIBA request whose authorization_details contains one payment_initiation entry: amount, currency, creditor account and a locations value naming the payments API. The user's phone shows "Approve payment of 50.00 EUR to ExampleCorp" with a binding code. On approval the agent receives a short-lived, sender-constrained token carrying exactly that entry, and the payments API refuses any other payee or amount. Vendor documentation for agent "asynchronous authorisation" describes this CIBA plus RAR pattern. See the OIDC CIBA Guide.

Why it matters

• Least privilege at transaction level: scopes like accounts.read grant a whole category for the token's life. RAR lets the grant name the resource, the action and the limits, which maps directly to NIST SP 800-53 AC-6 and CSF 2.0 PR.AA-05.
• Meaningful consent: users approve "this payment" rather than "access your payments", which is both better security and what payment regulation expects. FAPI 2.0 Security Profile recommends RAR when scope is not expressive enough.
• Smaller blast radius for stolen tokens: in the Salesloft Drift Breach 2025, stolen integration tokens let the attacker export bulk CRM records as the trusted app. Tokens limited to specific objects and actions would have offered far less. See the API Keys vs OAuth Tokens Guide.
• Agent governance: an agent acting for a user should carry evidence of what that user approved. RAR details in the token, combined with token exchange for downstream calls, give an auditable chain. See the OAuth Token Exchange and Delegation Guide and the AI Agent Authorisation Guide.

Scope or RAR?

The RFC allows both parameters in one request but recommends one form per API, so consent and enforcement stay predictable. Small organisations consuming SaaS APIs mostly meet RAR through providers; large organisations publishing APIs or deploying agents should design their own types.

Implementing RAR

1. Pick the first use case: one high-risk action where scopes are clearly too broad, such as payments or data exports by agents.
2. Write the type definition: fields, allowed values, which fields the user may change, whether the AS may enrich, and the comparison rule for "is this request narrower than the grant". Use a URI you control as the type name for widely deployed APIs.
3. Protect the request: require PAR or signed request objects; FAPI 2.0 already requires PAR with request_uri lifetimes under 600 seconds.
4. Enforce at the API: resource servers read authorization_details from the JWT or introspection and check every call against it. Without this step RAR is only decoration on the consent screen.
5. Test: run requests with unknown types, oversized arrays, injected markup in display fields and token requests that exceed the grant; all must fail.
6. Manage grants over time: where long-lived consents are needed, the OpenID Grant Management draft adds grant_id with create, merge and replace actions and a query and revoke endpoint. Roll back by revoking the grant, which must revoke its refresh tokens.

Detection and measurement

• Log: requested versus granted authorization_details, invalid_authorization_details errors by client, and resource server denials where a call exceeded the token's details. Watch for token theft and reuse (ATT&CK T1528, T1550.001).
• Metrics: share of sensitive API calls authorised by RAR rather than broad scopes; number of resource servers enforcing details; invalid_authorization_details rate per client; median token lifetime for RAR grants; number of active long-lived grants per user and agent.

Common misconceptions

• "RAR replaces scopes." It complements them; the RFC processes both together.
• "The AS will compare requests for me." There is no generic comparison algorithm and object equality is not enough. Each type must define it, or step-up and narrowing checks will be wrong.
• "What I requested is what I got." Users can grant a subset and the AS can enrich or omit values. Clients must read the token response.
• "Sending details in the front channel is fine." Unprotected details can be tampered with and can leak through referrer headers. Use PAR or signed and, for privacy, encrypted request objects.
• "Putting details in the token secures the API." Only if the resource server checks them. Many failures are APIs that validate the signature and scope and ignore the rest.
• "More detail is always better." The RFC's privacy section asks for minimal disclosure and need-to-know sharing with clients and resource servers.

Related concepts

Framework mapping

Practitioner checklist

• Inventory APIs where scopes grant more than a single transaction or resource needs.
• Publish type definitions with fields, enrichment rules and a comparison rule for each.
• Advertise authorization_details_types_supported and restrict each client to its registered types.
• Require PAR or signed request objects for every request carrying authorization_details.
• Sanitise and length-limit all values shown on consent screens.
• Enforce details at every resource server, not only at the AS.
• Pair RAR with CIBA for agent actions that need a human decision, and with DPoP or mTLS for the token.
• Review and revoke long-lived grants, and log requested versus granted details.

Standards and references

• IETF: RFC 9396 OAuth 2.0 Rich Authorization Requests
• OpenID Foundation: FAPI 2.0 Security Profile
• OpenID Foundation: OpenID Connect Client-Initiated Backchannel Authentication Flow, Core 1.0
• OpenID Foundation: OpenID for Verifiable Credential Issuance 1.0
• OpenID Foundation: Grant Management for OAuth 2.0
• Auth0: Asynchronous Authorization for AI Agents

Related NHI Mgmt Group resources: OAuth 2.0 and OpenID Connect Guide · OAuth Token Exchange and Delegation Guide · Agent Identity and Access Guide · DPoP Guide · OIDC CIBA Guide