When scopes need more detail
Your photo book uses the pictures in one album, album 42, from last summer at the lake. When the printer connects to your photo account, it asks for photos.read, and the photo service's consent screen says that Photo Printer wants to view your photos. You approve, because you want the book.
The token the printer receives can now read every photo in your library, including albums that have nothing to do with the book. The Grants, scopes, and consent lesson asked whether photos.read means every photo, one album, or photos shared with you. The scope name cannot say, and for some requests that missing detail is the whole decision.
One album, not the whole library
A scope is a name for a kind of access that the service defined in advance. photos.read works well for "read my photos" because the photo service can describe it once, show it on a consent screen, and check it at the API. It has no room for the part of the request that changes every time: which album.
The obvious workaround is to build the album into the scope string, as album-42.read or photos.read:42. The Scopes and audiences lesson explained why that breaks the fixed vocabulary that registrations, consent screens, and API checks rely on. The trouble goes further than one album. Every service that tried it would invent its own private format for where the identifier goes and how to handle characters a scope cannot contain, such as spaces and quotation marks, and every client would have to learn each format. When the printer needs a second album, or a different action on one of them, the strings multiply.
A scope parameter is a list of strings separated by spaces. Anything more structured than that has to be squeezed into a string by the client and parsed out again by the server.
One payment, exactly as approved
Now return to the Pay by bank checkout from The problem JAR solves, where the printer asks Lakeside Bank for authorization to make a 42.50 EUR payment for your photo book. At the bank, the printer is registered as the client photo-printer-pay.
Suppose the bank offered a scope called payments. Approving it would let the printer make payments from your account: any amount, to anyone, as many times as it liked while the token lasted. That is not what you agreed to. You agreed to pay 42.50 EUR, once, to Photo Printer, for one order.
Those details matter at both ends. The consent screen has to show them, because the amount and the recipient are what you are deciding. The bank's payment API has to enforce them: a payment of 43.00 EUR, a payment to a different account, or a second payment under the same approval must fail. Approval for one transaction with specific values is sometimes called transaction authorization. A scope string could carry it only through a private format such as pay:42.50:EUR:..., with all the problems of the album example and one more: a mistake in parsing an amount costs someone money.
Describing access as data
Rich Authorization Requests, published as RFC 9396 in May 2023, adds a request parameter called authorization_details. Its value is a JSON array. Each object in the array describes one piece of access the client wants, and its type field says what kind of access that is. The rest of the object is structured data whose meaning the type defines.
All domains, identifiers, and values in these examples are fictional. For the photo book, the printer could ask for this:
[
{
"type": "photo_album",
"actions": ["read"],
"identifier": "42"
}
]photo_album is a type the photo service defines for its own API. This object asks to read one album, the one identified as 42, and nothing else. Lakeside Bank would define its own type for payments, with fields for the amount, the currency, the receiving account, and a reference for the order.
The details travel through the same flow as a scope would, and each party has something to do with them:
| Party | What it does with the details |
|---|---|
| Client | Describes exactly what it needs, in the structure the type defines. |
| Authorization server | Checks each object against its type, shows it on the consent screen in plain language, and records what you approved. |
| Access token | Carries the approved details to the API, or lets the API look them up. |
| API | Enforces them on each request: album 42 can be read, other albums cannot. |
The API keeps every check it made before. Album 42 still has to be yours, and the token still has to be valid. Detailed authorization narrows what a token allows; it does not replace the API's own decisions.
Scopes and details together
Rich Authorization Requests does not retire scopes. A request can carry both, and the authorization server must process them together and show you the combined request on one consent screen. Scopes remain a good fit for broad, stable kinds of access, such as a calendar application's permission to read your events. The specification recommends that each API use one form or the other, so that its permissions are described in one place.
Authorization details cost more. The client builds JSON, the server needs a definition for every type and a way to present it, and the API has to understand the structure. They are worth that cost when a request contains values that change each time and that someone needs to see before approving: a particular album, an amount, a recipient, or a document to be signed.