Grants, scopes, and consent

Understanding grants

When the printing application requests access to your photos, several related decisions are involved.

What is it asking to do? Who can authorize that access? What does the authorization server actually issue? What will the photo API permit?

Three terms help us describe different parts of that process: grant, scope, and consent.

An authorization grant is a credential representing authorization that a client can use to obtain an access token. In the authorization code flow, the authorization code serves that purpose.

A grant type identifies the method used at the token endpoint. For example, the authorization code grant and client credentials grant use different credentials and serve different situations.

You may also hear a product refer to a saved application connection as a "grant." That describes the continuing authorization relationship recorded by the product. When reading a protocol exchange, it helps to distinguish that stored relationship from the credential being presented in a particular token request.

Describing access with scopes

A scope describes an area of access. Our fictional photo service might define:

photos.read
albums.create
photos.delete

The printer could request photos.read because it needs to retrieve photos. It has no reason to request photos.delete to create a printed book.

Those names are examples. Their meaning comes from the service that defines and enforces them. Another photo service could use different names or divide its capabilities differently.

Scope names are not universal instructions that an API automatically understands. Adding photos.read to a token request does not grant access by itself. The authorization server must decide whether to allow the request, and the API must enforce the resulting authorization.

A scope may also leave important questions unanswered.

Does photos.read permit reading every photo in your library? Only a selected album? Photos shared with your account?

The scope name alone does not tell us. The service needs rules and, where necessary, additional information to express those restrictions. Later, Rich Authorization Requests will examine one way to describe access requirements in more detail.

Consent and granted access

Consent is your agreement to the requested access. In our example, the photo service might show a screen explaining that the printer wants to read your photos.

Signing in and consenting are separate decisions. Signing in establishes control of your photo account. Approving the connection authorizes the printer to receive access.

A consent screen does not need to appear in every OAuth interaction. A service may already have a recorded authorization, or an organization may govern access through administrative policy. Some interactions involve a client acting on its own behalf.

Even when you approve a request, that approval cannot override every other rule. The application's registration, organizational restrictions, and the service's access policies may limit what can be issued.

The printer therefore needs to handle the access it actually receives. It should not assume that every requested capability was granted.

In Tokens and resource servers, we will follow that decision through to the API and examine how granted access is represented, checked, and rejected when a request exceeds it.