OAuth Scopes Explained: Fine-Grained API Authorization
A token without the right scopes is either useless or dangerous. This guide explains what OAuth scopes are, how to design a scope taxonomy, how scopes differ from roles, claims and audience, and how to enforce them at the API and gateway, with tested code.

TL;DR:
What are OAuth scopes?
OAuth scopes are space-separated strings, such asorders:read, that limit what an access token can do. A client asks for scopes when it requests a token, the authorization server grants some or all of them, and the API checks the token's scopes before allowing each call.
If a required scope is missing, the API returns403with aninsufficient_scopeerror.
A partner asks for "access to the orders API". Someone issues a token that can read, write and delete every order, for every customer, for a year. Six months later that token turns up in a leaked log file. Nothing about OAuth failed. The scopes did.
That isn't hypothetical. In August 2025, attackers used OAuth tokens stolen from the Salesloft Drift integration to pull data from hundreds of companies' Salesforce instances, according to Google's Threat Intelligence Group. A token is only as safe as what it's allowed to do, and OAuth scopes are what decide that.
This guide explains what scopes are, how they flow through a token request, how to design them, and how to enforce them, with code we ran and tested.

What are OAuth scopes?
OAuth scopes are the permissions attached to an access token. Each scope names something the token holder may do, such as reading orders or sending messages. The API trusts the token only for those things.
OAuth scope
An OAuth scope is a case-sensitive string that names a permission an access token may use. A token request carries a space-delimited list of scopes, and the authorization server can grant all of them, some of them, or none. The format is defined in RFC 6749, section 3.3, but the scope values themselves are chosen by each API.
Here's what an OAuth scope string looks like in a token request:
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=partner-221
&client_secret=...
&scope=orders:read%20orders:write
&resource=https://api.example.com/orders%20 is an encoded space, so this asks for two scopes: orders:read and orders:write. The resource parameter says which API the token is for. We cover it below.
Three rules from the standard matter in practice:
- Scopes are space-delimited.
orders:read orders:writeis two scopes, not one. - Scopes are case-sensitive.
Orders:Readandorders:readare different strings. - The server can grant fewer scopes than requested. When it does, it must say which scopes it granted in the
scopefield of the response.
What do OAuth scopes look like in real APIs?
OAuth doesn't define any standard scope names. Each provider designs its own, which is why API scopes look so different from one service to the next:
OAuth scope examples from real APIs
| Provider | Example scopes | Style |
|---|---|---|
| GitHub | repo, read:org, write:packages | Short names, action:resource |
https://www.googleapis.com/auth/drive.readonly | Full URLs | |
| Slack | chat:write, channels:read | resource:action |
| Microsoft Graph | Mail.Read, User.ReadWrite.All | Resource.Action |
| OpenID Connect | openid, profile, email, offline_access | Standard identity scopes |
Swipe sideways to see all columns →
The OIDC scopes are the one exception: OpenID Connect does define standard values. openid turns an OAuth request into a sign-in, profile and email release identity claims, and offline_access asks for a refresh token. They describe the user, not your API, so keep them separate from your API scopes.
How do OAuth scopes work?
Scopes travel through four steps: the client requests them, the authorization server grants them, the token carries them, and the API enforces them. Each step can narrow access. None should widen it.

- The client requests scopes. It sends the scopes it needs in the authorization or token request, plus the API it wants to call.
- The user consents, if there is one. In delegated flows, such as "Sign in with Google", the consent screen lists the scopes so the user can approve them. Machine-to-machine clients skip this step.
- The authorization server decides. It checks which scopes this client is allowed to have for this API, removes or rejects the rest, and puts the granted scopes into the token.
- The API enforces. For each request, it reads the token's
scopeclaim and checks that the scope the route needs is there. If not, it returns403 Forbiddenwitherror="insufficient_scope".
The token response tells the client what it got:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "orders:read"
}When the access token is a JWT, the granted scopes appear in its scope claim, as defined in RFC 9068. If you're new to that format, read what a JWT is.
How do OAuth scopes map to API permissions?
Each API operation should need exactly one scope, and each scope should cover a clear group of operations. A simple mapping makes enforcement and audits easy:
Mapping API operations to OAuth scopes
| Operation | Required scope | Why separate |
|---|---|---|
GET /orders, GET /orders/{id} | orders:read | Read-only access is the most common need |
POST /orders, PATCH /orders/{id} | orders:write | Creates and changes data |
DELETE /orders/{id} | orders:admin | Destructive; few clients should have it |
GET /orders/export | orders:export | Bulk data leaves your system; high risk |
POST /refunds | payments:refund | Moves money; separate from orders entirely |
Swipe sideways to see all columns →
Declare the same mapping in your OpenAPI file under securitySchemes, so the portal, the docs and the gateway all read the scope requirements from one place.
How do you design OAuth scopes?
Design scopes around resources and actions, split read from write, and give risky actions their own scopes. Good OAuth scopes best practices keep the list short enough to understand and narrow enough to matter.

Follow these rules:
- Name scopes
resource:action.orders:readis clear on a consent screen and easy to parse. Pick one style, colon or dot, and use it everywhere. - Split read from write. Most clients only read. Don't make them hold write access to do it.
- Give high-risk actions their own scope. Delete, export, refund and admin actions should never ride along with everyday write access.
- Avoid wildcards and catch-all scopes.
orders:*,adminor*turn a leaked token into full access. If you must have an admin scope, issue it only to a few internal clients with short token lifetimes. - Keep scopes stable. Clients hard-code scope names. Add new scopes rather than changing the meaning of old ones, and deprecate with notice.
- Don't encode tenants or users in scope names.
orders:read:acmeexplodes into thousands of scopes. Put the tenant in a claim and check it separately. - Document every scope in the developer portal: what it allows, which endpoints need it, and who can get it.
The opposite failure is scope explosion: hundreds of tiny scopes nobody can choose between. If you need a scope per customer, per field or per transaction, scopes are the wrong tool. Use claims, ABAC rules or rich authorization requests instead, as covered below.
How are OAuth scopes different from roles, claims and audience?
A scope limits what a client may do with a token. A role says what a user may do. A claim carries facts about the subject. The audience says which API the token is for. They answer different questions, and an API needs all four.
OAuth scopes vs roles, claims and audience
| Concept | Answers | Example | Who decides |
|---|---|---|---|
| Scope | What may this token be used for? | orders:read | Authorization server, per client and consent |
| Role | What may this user do in general? | support-agent | Your identity or directory system |
| Claim | What facts do we know about the subject? | tenant: acme, plan: gold | Authorization server or attribute sources |
Audience (aud) | Which API is this token for? | https://api.example.com/orders | Authorization server, from the resource parameter |
Swipe sideways to see all columns →
Two rules follow from the table.
A scope never adds to what a user can do. If a user can't delete orders, a token with orders:admin acting for that user still shouldn't. The effective permission is the intersection: what the token's scopes allow and what the user's own role allows.
Scopes and audience are not interchangeable. orders:read says "may read orders". It doesn't say whose orders API. Without an audience check, a token issued for one API can be replayed against another API that uses the same scope names. RFC 8707 (Resource Indicators) lets the client name the target API with a resource parameter, so the server can put it in aud and refuse scopes that API doesn't support.
For decisions that depend on roles and attributes, such as tenant or data class, see RBAC vs ABAC.
How do you enforce OAuth scopes?
Enforce scopes in two places: the authorization server limits what goes into the token, and the API checks the token on every request. Both checks are needed. The first keeps tokens narrow. The second catches anything that slips through.
Here's a minimal client credentials token endpoint in Node.js. It only grants scopes the client is registered for, for the API named in resource:
// token.mjs: client credentials token endpoint with scope and resource checks
// Node.js 18+, jose 5.x, Express 4.x
import express from 'express';
import { SignJWT, generateKeyPair } from 'jose';
import { randomUUID } from 'node:crypto';
const { privateKey, publicKey } = await generateKeyPair('RS256');
export { publicKey };
// What each client may ever receive, per API (resource)
const clients = {
'partner-221': {
secret: 's3cret-221',
grants: { 'https://api.example.com/orders': ['orders:read', 'orders:write'] },
defaultScopes: ['orders:read'],
},
};
export const tokenApp = express().use(express.urlencoded({ extended: false }));
tokenApp.post('/token', async (req, res) => {
const { grant_type, client_id, client_secret, scope, resource } = req.body;
const client = clients[client_id];
if (grant_type !== 'client_credentials' || !client || client.secret !== client_secret) {
return res.status(401).json({ error: 'invalid_client' });
}
const allowed = client.grants[resource]; // RFC 8707: which API is this token for?
if (!allowed) return res.status(400).json({ error: 'invalid_target' });
const requested = scope ? scope.split(' ').filter(Boolean) : client.defaultScopes;
const unknown = requested.filter((s) => !allowed.includes(s));
if (unknown.length) return res.status(400).json({ error: 'invalid_scope' });
const token = await new SignJWT({ scope: requested.join(' '), client_id })
.setProtectedHeader({ alg: 'RS256', typ: 'at+jwt' })
.setIssuer('https://auth.example.com').setAudience(resource)
.setSubject(client_id).setIssuedAt().setExpirationTime('10m').setJti(randomUUID())
.sign(privateKey);
res.json({ access_token: token, token_type: 'Bearer', expires_in: 600, scope: requested.join(' ') });
});And the API side. Each route declares the scope it needs, and a missing scope returns the response RFC 6750 defines:
// api.mjs: resource server that enforces scopes per route
import express from 'express';
import { jwtVerify } from 'jose';
import { publicKey } from './token.mjs';
const AUDIENCE = 'https://api.example.com/orders';
async function authenticate(req, res, next) {
const [scheme, token] = (req.headers.authorization || '').split(' ');
if (scheme !== 'Bearer' || !token) {
return res.status(401).set('WWW-Authenticate', 'Bearer').json({ error: 'missing_token' }); // no error code (RFC 6750)
}
try {
const { payload } = await jwtVerify(token, publicKey, {
algorithms: ['RS256'], issuer: 'https://auth.example.com', audience: AUDIENCE, typ: 'at+jwt',
});
req.scopes = new Set((payload.scope || '').split(' ').filter(Boolean)); // exact, case-sensitive tokens
next();
} catch {
res.status(401).set('WWW-Authenticate', 'Bearer error="invalid_token"').json({ error: 'invalid_token' });
}
}
// Every listed scope must be present as a whole token: no substring matching
const requireScopes = (...needed) => (req, res, next) =>
needed.every((s) => req.scopes.has(s))
? next()
: res.status(403)
.set('WWW-Authenticate', `Bearer error="insufficient_scope", scope="${needed.join(' ')}"`)
.json({ error: 'insufficient_scope' });
export const api = express().use(express.json());
api.get('/orders', authenticate, requireScopes('orders:read'), (req, res) => res.json({ orders: [] }));
api.post('/orders', authenticate, requireScopes('orders:write'), (req, res) => res.status(201).json({ id: 'ord_1' }));
api.delete('/orders/:id', authenticate, requireScopes('orders:admin'), (req, res) => res.status(204).end());We ran both against real requests:
OAuth scope enforcement test results
| Test | Result |
|---|---|
Request orders:read, then GET /orders | Token granted, 200 |
Same read-only token, POST /orders | 403, WWW-Authenticate: Bearer error="insufficient_scope", scope="orders:write" |
Request with no scope parameter | Token granted with the default orders:read |
Request orders:read orders:write, then POST /orders | 201 |
Same token, DELETE /orders/1 | 403, insufficient_scope, scope="orders:admin" |
Request orders:admin (not registered for this client) | 400 invalid_scope: no token issued |
Request Orders:Read (wrong case) | 400 invalid_scope |
| Request a token for the billing API | 400 invalid_target |
| Call the API with no token | 401, WWW-Authenticate: Bearer |
Swipe sideways to see all columns →

Why does exact scope matching matter?
Check scopes as whole, space-separated values, never as substrings. It's the most common scope bug in sample code online. A check like token.scope.includes('orders:read') returns true for a token whose only scope is orders:read_all. In our test, the substring check passed and the exact check correctly failed.
Should a missing scope return 401 or 403?
Return 403 when the token is valid but lacks the scope, and 401 when the token is missing or invalid. The WWW-Authenticate header tells the client which scope to ask for. A well-behaved client can then request a new token with that scope, instead of guessing.
How do you enforce OAuth scopes at the API gateway?
Map each route to its required scope at the gateway, so every API enforces scopes the same way before traffic reaches your services. Kong, Apigee, AWS API Gateway and Azure API Management can all check a JWT's scope claim per route.
The problem is drift. One gateway checks orders:write on POST /orders, another forgets the export route, and a third still accepts a retired orders:all scope. The DigitalAPI API Gateway applies the same scope-to-route policy across the gateways you already run, so a scope change happens once. Teams using the DigitalAPI API Developer Portal let partners request only the scopes their plan allows and see exactly what each scope unlocks, so access is narrow from the first token.
See how DigitalAPI enforces the same OAuth scopes across every gateway you run → Book a Demo
When are OAuth scopes not enough?
Scopes are coarse by design: they say what kind of action a token may take, not on which object, for how much, or under what conditions. For fine grained authorization, pair scopes with claims and policy, or use rich authorization requests. For how scopes fit alongside roles, attributes and relationships, see our guide to API authorization.
Three common cases:
- "Only this tenant's data." A scope can't say whose orders. Put the tenant in a claim and check it against each object. That's the fix for Broken Object Level Authorization, which the OWASP API Security Top 10 (2023) ranks first. See what is ABAC for the policy pattern.
- "Only this payment, for this amount." Use Rich Authorization Requests (RFC 9396), published in 2023. Instead of a scope string, the client sends a structured
authorization_detailsobject. - "Only for the next five minutes, only this tool." Issue short-lived tokens with a narrow scope, or exchange a broad token for a narrower one with OAuth Token Exchange (RFC 8693) before calling a downstream API.
Here's what a rich authorization request looks like for a single payment. This follows the structure in RFC 9396:
[
{
"type": "payment_initiation",
"actions": ["initiate"],
"locations": ["https://api.example.com/payments"],
"instructedAmount": { "currency": "EUR", "amount": "123.50" },
"creditorName": "Merchant A",
"creditorAccount": { "iban": "DE02100100109307118603" }
}
]A scope like payments:initiate would allow any payment. This object allows one payment of €123.50 to one account. Open banking profiles such as FAPI 2.0 use this pattern for exactly that reason.
How do OAuth scopes work for AI agents and MCP servers?
Give each AI agent its own client, the narrowest scopes for the tools it uses, and minutes-long tokens. Agents act fast and unattended, so a broad scope turns one bad prompt into a large blast radius.
The MCP authorization specification builds on these same standards. MCP servers publish their supported scopes through Protected Resource Metadata (RFC 9728), clients use the resource parameter from RFC 8707, and servers must only accept tokens issued for them. Map one scope to each group of tools, such as tickets:read and tickets:write, and keep write and export tools behind separate scopes. For the full setup, see securing MCP endpoints.
What are the most common OAuth scope mistakes?
Most scope failures come from scopes that are too broad, checked too loosely, or never checked at all. Broken Function Level Authorization, where callers reach functions they shouldn't, is number five in the OWASP API Top 10 (2023), and missing scope checks are a common cause. Watch for these:
Common OAuth scope mistakes and fixes
| Mistake | What happens | Fix |
|---|---|---|
One scope for everything (api, full_access, *) | A leaked token can do anything | Split by resource and action |
| Read and write in one scope | Read-only clients hold write access | Separate :read and :write |
| Granting whatever the client asks for | Clients request admin "just in case" | Allowlist scopes per client and per API |
| Substring scope checks | orders:read_all passes an orders:read check | Split on spaces and match exact values |
| No audience check | A token for one API works on another | Use resource (RFC 8707) and verify aud |
| Checking scopes only at the gateway, or only in the service | Routes added later skip the check | Enforce at the gateway and keep a check in the service |
| Tenant or user IDs in scope names | Thousands of scopes, scope explosion | Put identifiers in claims, check with policy |
| Long-lived tokens with broad scopes | Stolen tokens work for months | Short lifetimes; refresh or re-request |
| Never reviewing granted scopes | Unused scopes stay granted for years | Log scope use; remove what clients don't use |
Returning 401 for a missing scope | Clients retry with the same token | Return 403 with insufficient_scope |
Swipe sideways to see all columns →
The cost of over-broad access is well documented. Salt Security's 2025 State of API Security report found that 95% of API attacks came from authenticated sources, and the Verizon 2025 Data Breach Investigations Report found credential abuse was the top way attackers got in, at 22% of breaches. Narrow scopes don't stop credentials from leaking. They limit what a leaked credential can do.
Key takeaways
- OAuth scopes limit what an access token can do: space-separated, case-sensitive strings such as
orders:read. - Narrow at every step: clients request only what they need, the authorization server grants only what's allowed, and the API checks every call.
- Design
resource:actionscopes, split read from write, and give delete, export, refund and admin their own scopes. - Scopes aren't roles, claims or audience. Effective access is the token's scopes intersected with the user's rights, for the API named in
aud. - Enforce exactly: whole-value matching,
403 insufficient_scopefor missing scopes, and one scope policy across every gateway.
Frequently asked questions
1. What is a scope in OAuth?
A scope in OAuth is a string that names a permission an access token may use, such as orders:read. The client asks for scopes when requesting a token, the authorization server grants all or some of them, and the API checks the token's scopes before allowing each request. Scopes are space-separated and case-sensitive.
2. What is an example of an OAuth scope?
Common OAuth scope examples include GitHub's repo and read:org, Slack's chat:write, Microsoft Graph's Mail.Read and Google's https://www.googleapis.com/auth/drive.readonly. For your own API, a clear pattern is resource:action, such as orders:read, orders:write and payments:refund.
3. Is an OAuth scope the same as a role?
No. A role describes what a user is allowed to do in general, such as "support agent". A scope limits what a specific token may be used for, such as reading orders. A token's effective access is the overlap of both: a scope can't give a user more rights than their role allows.
4. What is the difference between OAuth scopes and claims?
Scopes are the permissions a token may use, chosen at request time. Claims are facts about the subject carried in the token, such as user ID, tenant or email. Scopes answer "what may this token do?" and claims answer "who or what is this about?". Fine-grained checks usually need both.
5. What are OIDC scopes?
OIDC scopes are the standard scopes defined by OpenID Connect: openid, which makes the request a sign-in and returns an ID token, plus profile, email, address and phone, which release identity claims. offline_access requests a refresh token. They describe the user, not your API, so keep them separate from API scopes.
6. What error should an API return when a scope is missing?
An API should return HTTP 403 Forbidden with the header WWW-Authenticate: Bearer error="insufficient_scope", scope="...", as defined in RFC 6750. The scope value tells the client which scope it needs. Use 401 only when the token is missing, expired or otherwise invalid.
7. How many OAuth scopes should an API have?
Enough to separate read, write and high-risk actions for each resource, and no more. Many APIs need two or three scopes per resource, such as orders:read, orders:write and orders:export. If you find yourself creating scopes per customer, per field or per record, use claims or policy rules instead.
8. What is the difference between scope and audience in OAuth?
Scope says what a token may do, such as orders:read. Audience, the aud claim, says which API the token is for. Both must be checked. Without an audience check, a token issued for one API can be replayed against another API that happens to use the same scope names.
9. What are Rich Authorization Requests?
Rich Authorization Requests (RAR), defined in RFC 9396 in 2023, let a client request fine-grained permissions as a structured JSON object called authorization_details, instead of a flat scope string. They're used when access depends on specific values, such as a single payment of a set amount to a set account in open banking.
10. Can OAuth scopes change after a token is issued?
No. A token's scopes are fixed when it's issued. To get more scopes, the client requests a new token, which may need fresh consent. To get fewer, it can request a narrower token or use token exchange. Short token lifetimes make scope changes and revocations take effect quickly.
Conclusion
OAuth scopes are the simplest fine-grained control you have: a short string that decides what a token may do. Used well, a leaked token can only read what it was meant to read, for a few minutes. Used badly, scopes become a rubber stamp that says "full access" in a slightly longer way.
Keep scopes resource:action, split read from write, isolate risky actions, check audience alongside scope, and enforce exactly, at the gateway and in the service. When you need "this tenant" or "this payment", reach past scopes to claims, policy and rich authorization requests.
How safely do you grant API access to partners and AI agents? Get your free readiness score: Check Your API Access Readiness
Prefer a walkthrough? Book a Demo
One email a fortnight. Worth opening.
A short digest of what we're writing, what we're learning from customers, and the handful of links you'd actually want from us. No tracking pixels.













.avif)
