Scope-Based Permissions
A permission model where access tokens carry scope strings that define the specific actions and resources the token is authorized to access.
Description
Scope-based permissions is an authorization model used in OAuth 2.0 where access tokens are issued with a defined set of scopes -- string identifiers that represent specific permissions or access levels. The client requests scopes during the authorization flow, the user (or authorization server for client credentials) approves them, and the resulting token can only be used for operations within those scopes. Resource servers enforce scope requirements, rejecting requests from tokens that lack the necessary scope.
Scopes follow various naming conventions: simple names (read, write, admin), hierarchical names (user:read, user:write, repo:admin), or URI-based names (https://api.example.com/scopes/read). The choice depends on the API's complexity and the granularity needed. OpenID Connect defines standard scopes (openid, profile, email, address, phone) for identity-related claims. Best practice is to design scopes that are coarse enough to be manageable but fine enough to support least-privilege access -- a common pattern is resource:action (orders:read, orders:write, users:delete).
Scope enforcement happens at multiple layers: the authorization server validates that requested scopes are within the client's allowed set, the token includes only granted scopes, and resource servers check that the token's scopes include the required scope for each endpoint. In JWT-based systems, scopes are typically included in a scope claim (space-delimited string) or a permissions claim (JSON array). Middleware or route decorators check the scope before allowing the request to proceed. Dynamic scope consent screens show users exactly what permissions they are granting, which is critical for third-party applications.
Prompt Snippet
Implement scope-based permissions using a resource:action naming convention (e.g., 'users:read', 'orders:write', 'admin:manage'). Store allowed scopes per client in the OAuth client registration. Include granted scopes as a space-delimited scope claim in JWT access tokens. Create authorization middleware that extracts the scope claim from the JWT and checks it against the required scopes for the route: @RequiresScope('orders:write'). Support hierarchical scope matching where 'orders:*' grants all order-related permissions. Return 403 Forbidden with a WWW-Authenticate header specifying the required scope when access is denied due to insufficient scopes.Tags
Related Terms
OAuth 2.0
An authorization framework that enables third-party applications to obtain limited access to a web service on behalf of a resource owner.
RBAC (Role-Based Access Control)
An access control model where permissions are assigned to roles, and users are granted roles, simplifying permission management at scale.
ABAC (Attribute-Based Access Control)
An access control model that evaluates policies against attributes of the user, resource, action, and environment to make authorization decisions.
API Key Scoping & Rotation
The practice of limiting API key permissions to specific resources and operations, and regularly replacing keys to minimize the impact of compromise.
Claims-Based Identity
An identity model where user attributes and permissions are expressed as claims -- name-value pairs -- embedded in tokens or assertions, enabling decoupled and portable identity.
Authorization Code Grant
An OAuth 2.0 grant type where the client receives an authorization code via a browser redirect and exchanges it server-side for tokens, keeping tokens off the front channel.