OAuth Scopes

OAuth scopes are space-delimited strings that request and limit delegated access. Resource servers must enforce them; they do not authenticate users or replace authorization logic.

security

Definition

OAuth scopes are case-sensitive strings, sent space-delimited, that a client requests to describe the delegated access it needs. The authorization server may narrow them, records the granted set in the access token, and resource servers are expected to enforce that set before performing an operation.

Context and scope

Scopes appear in OAuth 2.0 authorization requests, consent screens, access token responses, and introspection results. They are the primary tool for limiting third-party and service-to-service access.

Common misconceptions

Granting a scope automatically enforces it on every API endpoint
Scopes identify the user or prove that the user was authenticated

Anti-patterns

Requesting a wildcard or admin scope for every client to avoid scope design
Checking scopes only in the UI while backend routes remain unprotected

Related concepts

Related examples

Authoritative source

https://www.rfc-editor.org/rfc/rfc6749#section-3.3

How scopes work

A client requests space-delimited scope strings at the authorization endpoint. The authorization server may show them on a consent screen, narrow them, and records the granted set in the access token. The resource server must check the token’s scope claim before serving each operation. Scopes are names, not permissions by themselves: their meaning comes from the API documentation and the enforcement code.

When to use scopes

Use scopes for delegated access, third-party integrations, and least-privilege tokens. A read-only dashboard should request orders:read, not orders:admin. Pair coarse scopes with resource-level checks: an orders:read token must still verify that the order belongs to the user. Scopes differ from roles, because roles describe who the user is inside a tenant while scopes limit what a particular client token may do. Compared with roles, scopes travel with the token and constrain the client, not the user.

Trade-offs

Fine-grained scopes improve least privilege but multiply consent text and token size, and clients may request more than they need. Too few scopes push authorization decisions into application code, where they are easy to forget. Downscoping at token exchange adds complexity. Renaming a scope is a breaking API change, so version scope vocabularies deliberately.

Example

GET /authorize?response_type=code&client_id=app1
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcb
  &scope=profile%20orders%3Aread HTTP/1.1

The token response includes "scope": "profile orders:read". A request to POST /orders without orders:write should return 403 insufficient_scope, not a generic server error.

Scopes do not prove user identity; OpenID Connect provides authentication. Granting a scope is not the same as enforcing it, and a missing check silently widens access. Wildcards such as * defeat least privilege. Combine scopes with audience restrictions, and review them alongside OAuth 2.0 PKCE and JWT validation.