Scopes and claims are different
A scope is a coarse permission attached to a token, such as read orders or write profile. It bounds what the token may do. A claim is a statement of fact about the subject, such as the user id, the tenant, or an email.
Scopes answer what may I do. Claims answer who is this and what do we know about them.
Designing scopes well
- Keep scopes coarse and stable so clients request only what they need.
- Avoid one scope per endpoint, which explodes into an unmanageable list.
- Group by resource and action, like orders read and orders write.
Designing claims well
- Include only stable, low sensitivity facts that downstream services genuinely need.
- Avoid putting fast changing data in claims, since a token is a snapshot.
- Keep the token small; every claim travels on every request.
Least privilege
Request the minimum scopes for the task. A token that can read should not also be able to delete unless that work requires it.
Key idea
Scopes bound what a token may do while claims state facts about the subject, and both should stay minimal and stable under least privilege.