Join our Newsletter — 33% off our NHI Course
Home› Guides› OAuth Scope Design Guide: Naming, Granularity and Least…
Guide SaaS & OAuth Integrations

OAuth Scope Design Guide: Naming, Granularity and Least Privilege for APIs

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 13 min read
On this page

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:write and orders:refund gives 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 scope in the token response. If the client omits scope, the server applies a documented default or rejects with invalid_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 scope or authorization_details.
  • JWT access tokens (RFC 9068): the token should carry a scope claim when scope was requested, and each scope value must have meaning for the resources in aud. Where no resource parameter is sent, the server infers a default audience from the scopes, and should reject with invalid_scope if the scopes point to different resources.
  • Group, role and entitlement claims: RFC 9068 suggests the SCIM attribute names groups, roles and entitlements for 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.

ConventionExampleSeen atStrength and weakness
Resource URI plus permissionhttps://graph.microsoft.com/Calendars.ReadMicrosoft identity platformAudience is explicit in the string; long, and a bare User.Read silently defaults to Microsoft Graph
URL per capabilityhttps://www.googleapis.com/auth/calendar.readonlyGoogle APIsGlobally unique; harder to read and to group
Prefix and actionread:org, admin:org, repo:statusGitHub OAuth appsShort and readable; hierarchy is implicit and easy to misread (repo gives full private repository access)
Resource and actioninvoices:read, invoices:approveCommon internal API patternMaps cleanly to API routes; needs a registry to stop drift
  • Pick one separator and one verb set: for example read, write, delete, admin plus named business actions. Avoid synonyms such as modify and update in the same API.
  • Name the resource, not the client: reports:read, not bi-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, email and offline_access have 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.

GranularityExampleWhen it fitsRisk
API-wideapiNever for external clients; at most for a single first-party back endAny token can do anything the user can
Read versus write per APIcrm.read, crm.writeSmall APIs with one resource typeWrite usually implies delete and admin
Resource and actioncontacts:read, contacts:exportMost business APIs; the default recommendationScope count grows with the API; needs a registry
Field or property levelcontacts.email:readHighly sensitive fields (health, payment, national ID)Explodes quickly; better handled in RS policy
Per transactionRAR authorization_details with amount and accountPayments, signing, high-value approvalsRequires 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 export scope 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:write implies orders: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 resource parameter (RFC 8707) or resource-qualified scope strings so a token for the reporting API cannot be replayed at the payments API.
  • Distinct aud per resource server: RFC 9068 requires the authorisation server to use a distinct aud for each resource to prevent cross-JWT confusion, and resource servers must reject tokens whose aud does not include them.
  • Do not reuse scope names across APIs: a generic read accepted 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.All and Directory.ReadWrite.All) as requiring administrator consent, so ordinary users cannot grant them.
  • Refresh capability: treat offline_access as 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

  1. Validate the token first: signature, issuer, expiry, aud and, for constrained tokens, the proof of possession.
  2. 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.
  3. 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.
  4. Return the right error: 403 with error="insufficient_scope" and the required scope in the WWW-Authenticate header lets well-behaved clients request incremental consent.
  5. Expose scope requirements: GitHub returns X-OAuth-Scopes (what the token has) and X-Accepted-OAuth-Scopes (what the endpoint checks), which makes over-requesting easy to spot.
  • 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 scope and degrade gracefully.
  • Bundle carefully: static bundles such as Entra ID .default are 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

FrameworkReferenceHow scope design supports it
NIST SP 800-53 Rev 5AC-6 Least Privilege, AC-3 Access EnforcementMinimal scopes per client; enforcement at the resource server
NIST SP 800-53 Rev 5AC-2 Account Management, AU-6Client and grant inventory, review of grant and usage logs
NIST CSF 2.0PR.AA-05Permissions defined, managed and reviewed with least privilege
OWASP API Security Top 10 2023API1, API3, API5Scopes complement, but do not replace, object and function checks
MITRE ATT&CKT1528 Steal Application Access Token, T1550.001 Application Access TokenScope 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

  1. Inventory routes and current scopes: list every endpoint, the scope that protects it today and which clients call it.
  2. Draft the model: resources, actions, sensitive tiers and implied relationships, reviewed by API owners and security.
  3. Publish a registry: one source for scope strings, descriptions, tiers and owners, used by the authorisation server, documentation and gateway policy.
  4. 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.
  5. 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.
  6. 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: write covers 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:read but 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 aud does 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_scope errors 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.