Most OAuth integrations end up with far more access than they use, because the API offered a handful of coarse scopes and every client asked for the broadest one. Once a token is stolen or a vendor is breached, the scope is the blast radius. Scope design is an API design decision that is hard to change after clients ship, so it pays to get it right early. This guide is for API owners, identity architects and platform teams who define scopes for their own APIs and authorisation servers: naming, granularity, how scopes relate to audience and fine-grained authorisation, how to handle machine clients, and how to measure and evolve scopes over time. For governing third-party apps that request scopes against your SaaS tenants, see the SaaS OAuth App Governance Guide.
Key takeaways
- A scope is a ceiling, not a permission check: it limits what a client may do on a user's or its own behalf, and the resource server must still enforce object-level and function-level authorisation.
- Design scopes around resources and actions: a pattern such as
orders:read,orders:writeandorders:refundgives clients a least-privilege choice without hundreds of strings. - Bind scope to audience: RFC 9700 says access tokens should be restricted to the minimum required and audience-restricted to a specific resource server; a scope that means different things at different APIs invites token reuse.
- Keep dangerous actions in their own scopes: admin, delete, export, payment and credential management should never ride along with a general write scope.
- Scopes are not enough for transaction detail: use Rich Authorization Requests (RFC 9396) when consent must name an amount, account or specific object.
What a scope is, according to the standards
- Syntax (RFC 6749 section 3.3): a space-delimited list of case-sensitive strings; each token uses printable ASCII except space, double quote and backslash; order does not matter.
- Server discretion: the authorisation server may grant less than requested and must then return the granted
scopein the token response. If the client omits scope, the server applies a documented default or rejects withinvalid_scope. - Least privilege and audience (RFC 9700 section 2.3): privileges should be restricted to the minimum required, tokens should be audience-restricted, and resource servers must refuse requests a token was not issued for. Tokens should be limited to certain resources and actions using
scopeorauthorization_details. - JWT access tokens (RFC 9068): the token should carry a
scopeclaim when scope was requested, and each scope value must have meaning for the resources inaud. Where noresourceparameter is sent, the server infers a default audience from the scopes, and should reject withinvalid_scopeif the scopes point to different resources. - Group, role and entitlement claims: RFC 9068 suggests the SCIM attribute names
groups,rolesandentitlementsfor authorisation attributes beyond delegation. These describe the subject; scopes describe what the client was allowed to do with the subject's authority.
For the overall OAuth model see the OAuth 2.0 and OpenID Connect Guide, and for the full set of BCP controls the OAuth 2.0 Security Best Current Practice (RFC 9700) Guide.
Naming conventions
Large providers use different conventions. None is mandated; consistency inside your own platform matters more than which you choose.
| Convention | Example | Seen at | Strength and weakness |
|---|---|---|---|
| Resource URI plus permission | https://graph.microsoft.com/Calendars.Read | Microsoft identity platform | Audience is explicit in the string; long, and a bare User.Read silently defaults to Microsoft Graph |
| URL per capability | https://www.googleapis.com/auth/calendar.readonly | Google APIs | Globally unique; harder to read and to group |
| Prefix and action | read:org, admin:org, repo:status | GitHub OAuth apps | Short and readable; hierarchy is implicit and easy to misread (repo gives full private repository access) |
| Resource and action | invoices:read, invoices:approve | Common internal API pattern | Maps cleanly to API routes; needs a registry to stop drift |
- Pick one separator and one verb set: for example
read,write,delete,adminplus named business actions. Avoid synonyms such asmodifyandupdatein the same API. - Name the resource, not the client:
reports:read, notbi-tool. Client-named scopes become bundles that nobody can review. - Write a human description for every scope: it appears on consent screens and in admin reviews. "Read your calendar events" beats "calendar access".
- Reserve OpenID Connect scopes:
openid,profile,emailandoffline_accesshave defined meanings; do not reuse them for API access.
Choosing the right granularity
Too coarse and every client is over-privileged; too fine and developers request everything to make the app work, consent screens become unreadable and nobody can review grants.
| Granularity | Example | When it fits | Risk |
|---|---|---|---|
| API-wide | api | Never for external clients; at most for a single first-party back end | Any token can do anything the user can |
| Read versus write per API | crm.read, crm.write | Small APIs with one resource type | Write usually implies delete and admin |
| Resource and action | contacts:read, contacts:export | Most business APIs; the default recommendation | Scope count grows with the API; needs a registry |
| Field or property level | contacts.email:read | Highly sensitive fields (health, payment, national ID) | Explodes quickly; better handled in RS policy |
| Per transaction | RAR authorization_details with amount and account | Payments, signing, high-value approvals | Requires RAR support in AS, client and RS |
- Split by risk, not by endpoint count: group harmless read endpoints together, but give bulk export, delete, permission changes, credential management and money movement their own scopes.
- Separate read from bulk read: pagination through every record is an exfiltration capability. An
exportscope with tighter limits and logging makes the difference visible. - Do not encode tenant or object IDs in scope strings: that is authorisation data. Use RAR or resource server policy instead. See the OAuth Rich Authorization Requests (RAR) Guide.
- Keep hierarchy explicit: if
orders:writeimpliesorders:read, document it and enforce it in one place. GitHub, for example, normalises overlapping requests and drops implied scopes.
Scopes, audiences and resource indicators
- One audience per token: RFC 9700 recommends audience-restricted tokens. Use the
resourceparameter (RFC 8707) or resource-qualified scope strings so a token for the reporting API cannot be replayed at the payments API. - Distinct
audper resource server: RFC 9068 requires the authorisation server to use a distinctaudfor each resource to prevent cross-JWT confusion, and resource servers must reject tokens whoseauddoes not include them. - Do not reuse scope names across APIs: a generic
readaccepted by several services turns every token into a multi-service token. - Sender-constrain high-value tokens: mTLS (RFC 8705) or DPoP (RFC 9449) means a stolen token with a broad scope is still hard to use.
Delegated versus application scopes
Scopes for a user-delegated client and for a machine client should not be the same list.
- Delegated: the effective access is the intersection of the scope and the user's own rights. GitHub's documentation puts it plainly: scopes only narrow access and never add permissions the user lacks.
- Application (client credentials): the client acts as itself, so the scope is the whole permission. In Microsoft Entra ID, application permissions are granted directly by an administrator and a client credentials request must ask for
{resource}/.default, which returns every app role granted to that client. Granularity must therefore be designed into the app roles, because the client cannot down-scope at request time. - Admin-only scopes: mark tenant-wide scopes (Entra ID examples include
User.Read.AllandDirectory.ReadWrite.All) as requiring administrator consent, so ordinary users cannot grant them. - Refresh capability: treat
offline_accessas a privilege in its own right. In Entra ID it is implied by any delegated grant, but the client must still request it to receive refresh tokens.
See the Machine-to-Machine OAuth (Client Credentials) Guide and the API Keys vs OAuth Tokens Guide.
Enforcing scopes in the resource server
- Validate the token first: signature, issuer, expiry,
audand, for constrained tokens, the proof of possession. - Map every route to a required scope: keep the mapping in code or policy beside the route, and fail closed when a route has no mapping.
- Then check object and property access: scope alone does not stop a client reading another tenant's object. The OWASP API Security Top 10 2023 lists API1:2023 Broken Object Level Authorization, API3:2023 Broken Object Property Level Authorization and API5:2023 Broken Function Level Authorization; scope checks address only part of API5.
- Return the right error:
403witherror="insufficient_scope"and the requiredscopein theWWW-Authenticateheader lets well-behaved clients request incremental consent. - Expose scope requirements: GitHub returns
X-OAuth-Scopes(what the token has) andX-Accepted-OAuth-Scopes(what the endpoint checks), which makes over-requesting easy to spot.
Consent, review and publishing
- Classify scopes by sensitivity: Google classifies scopes as non-sensitive, sensitive and restricted, and requires a justification for each sensitive scope, including why a narrower scope will not work. Adopt the same tiers for your API and require review for the upper tiers.
- Request incrementally: clients should ask for the minimum at sign-in and add scopes when the user reaches the feature that needs them.
- Handle partial grants: users and admins can grant fewer scopes than requested; clients must read the returned
scopeand degrade gracefully. - Bundle carefully: static bundles such as Entra ID
.defaultare convenient but hide the list from the user. Use them for back-end and admin-consented apps, not consumer consent.
Decision guidance by organisation and architecture
- Small API, few clients: start with read and write per resource plus separate scopes for the two or three dangerous actions. Add finer scopes when a real client needs less than an existing scope gives.
- Public API platform with many third parties: resource and action scopes, sensitivity tiers with review, mandatory incremental consent and published scope requirements per endpoint. Expect to support deprecated scopes for a long time, so design carefully before launch.
- Microservices behind a gateway: do not pass the user's broad edge token from service to service. Exchange it for a narrower, audience-specific token at each hop (RFC 8693 token exchange) or use transaction tokens. See the OAuth Token Exchange and Delegation Guide.
- AI agents and automation: agents should receive task-scoped, short-lived tokens rather than the full set their user could grant; a scope model with separate export and write actions makes that possible.
Where identity fits
Every OAuth client is a non-human identity, and its granted scopes are its entitlements. Inventory clients and their scopes like any other machine account: owner, purpose, last use, and a review that removes scopes not used in 90 days. The Salesloft Drift breach shows the cost of skipping this: one chatbot integration held broad, long-lived access to customers' Salesforce data, and stolen tokens were used to bulk export accounts, contacts, users and support cases across hundreds of tenants.
Framework mapping
| Framework | Reference | How scope design supports it |
|---|---|---|
| NIST SP 800-53 Rev 5 | AC-6 Least Privilege, AC-3 Access Enforcement | Minimal scopes per client; enforcement at the resource server |
| NIST SP 800-53 Rev 5 | AC-2 Account Management, AU-6 | Client and grant inventory, review of grant and usage logs |
| NIST CSF 2.0 | PR.AA-05 | Permissions defined, managed and reviewed with least privilege |
| OWASP API Security Top 10 2023 | API1, API3, API5 | Scopes complement, but do not replace, object and function checks |
| MITRE ATT&CK | T1528 Steal Application Access Token, T1550.001 Application Access Token | Scope limits what a stolen token can do |
Detection and measurement
- Log granted scope per token issuance and used scope per request: the gap between them is your over-privilege.
- Alert on first use of a sensitive scope by a client, on bulk export scopes outside normal hours and on new grants of admin scopes.
- Metrics: share of clients holding at least one scope unused in 90 days; average scopes granted versus used per client; number of clients with admin or export scopes; share of routes with an explicit scope mapping; time to remove a scope from all clients after deprecation.
How to roll out a scope model
- Inventory routes and current scopes: list every endpoint, the scope that protects it today and which clients call it.
- Draft the model: resources, actions, sensitive tiers and implied relationships, reviewed by API owners and security.
- Publish a registry: one source for scope strings, descriptions, tiers and owners, used by the authorisation server, documentation and gateway policy.
- Run new scopes in parallel: issue both old and new scopes, log which routes would deny under the new mapping (audit mode) and fix gaps before enforcing.
- Migrate clients: first-party clients first, then partners, with deadlines. Keep the old broad scope working but mark it deprecated and alert on its use.
- Enforce and remove: switch routes to new scopes, then stop issuing the old scope. Rollback is re-enabling the old mapping, which is why it stays in the registry until the last client migrates.
Common failure patterns
- One write scope for everything:
writecovers update, delete, export and permission changes, so every integration that needs to update a field can also wipe data. - Scopes without audience: generic scope names are accepted by several APIs and a token minted for one is replayed at another.
- Treating scope as authorisation: the API checks
orders:readbut not whether the order belongs to the caller's tenant. - Machine clients with user-style scopes: application permissions granted tenant-wide because the delegated scope list was reused.
- Scope creep through bundles: a static bundle grows as features are added and every client inherits the new rights silently.
- No usage data: nobody can say which scopes a client actually uses, so reviews never remove anything.
Practitioner checklist
- Adopt one naming convention and a verb set, and publish a scope registry with descriptions, owners and sensitivity tiers.
- Give export, delete, admin, credential and payment actions their own scopes.
- Audience-restrict every token and reject tokens whose
auddoes not match. - Design machine client permissions as app roles with the same granularity as delegated scopes.
- Map every route to a required scope and fail closed for unmapped routes.
- Enforce object and property level authorisation in addition to scope.
- Return
insufficient_scopeerrors so clients can request incremental consent. - Log granted versus used scopes and remove scopes unused for 90 days.
- Use RAR for transaction-level consent instead of inventing per-object scopes.
Standards and references
- IETF: RFC 6749 The OAuth 2.0 Authorization Framework, section 3.3 Access Token Scope
- IETF: RFC 9700 Best Current Practice for OAuth 2.0 Security
- IETF: RFC 9068 JWT Profile for OAuth 2.0 Access Tokens
- IETF: RFC 8707 Resource Indicators for OAuth 2.0
- IETF: RFC 9396 OAuth 2.0 Rich Authorization Requests
- Microsoft Learn: Scopes and permissions in the Microsoft identity platform
- GitHub Docs: Scopes for OAuth apps
- OWASP: API Security Top 10 2023
Related NHI Mgmt Group resources: SaaS OAuth App Governance Guide · OAuth 2.0 Security Best Current Practice (RFC 9700) Guide · OAuth Rich Authorization Requests (RAR) Guide · OAuth Step-Up Authentication Challenge Guide