Card 05/ 11
Scopes and Consent
A scope names what a token allows, and the user sees the scopes before agreeing.
A scope is a string naming a permission a token carries, such as photos.read. The client asks for scopes when it starts a flow, the user sees them on the consent screen and approves, and the token records the scopes granted. The resource server checks the token's scopes on every request and refuses anything they do not cover, with 403.
| Scope | Allows | API calls covered |
|---|---|---|
| photos.read | Reading photos and albums | GET /photos, GET /albums |
| photos.write | Uploading and editing photos | POST /photos, PATCH /photos/{id} |
| photos.delete | Deleting photos | DELETE /photos/{id} |
| profile | Reading the user's name and picture | GET /me |
Ask for the least that works. The printing app needs photos.read and nothing else. A client that asks for everything sees more users refuse, and does more damage if its tokens leak.
The consent screen. It translates scopes into plain words, "Read your photos", so the user knows what they agree to. A user who has consented once may not be asked again for the same scopes.
Fewer than asked. The authorization server may grant fewer scopes than requested, because the user unticked one or a policy forbids it. The token response lists the scopes granted, and the client must check that list rather than assume.
Scopes are not all of authorisation. A token with photos.read lets the client read photos, but only the user's own. The API still checks that each photo belongs to the token's user.
So design scopes around the actions clients need, check them on every request, and still check which user's data is being touched.
← → move through sections and cards