OAuth 2.0 Scopes

The Bound of Authority

Scopes are the primary mechanism used in OAuth 2.0 to limit an application’s access to a user’s account. They are not permissions themselves, but rather requested capabilities that define the “area of influence” an Access Token holds.

SCOPES

Access Granularity

Core Mission

Least Privilege Enforcement. Ensuring a client application can only perform the specific actions the user has explicitly approved.

Like a Hotel Keycard: It's not a master key. It is scoped exactly to your room number and the gym. It won't open the kitchen or the laundry room, regardless of who is holding it.

Permission Delegation / API Security

The Scope Lifecycle

Scopes transition from a client’s request to a user’s consent, and finally to a cryptographic claim within a token.

1

Request

The client requests one or more space-separated scope strings (e.g., `read:photos write:comments`) during the initial redirect.

2

Consent

The Authorization Server presents these requests to the user. The user can approve all, some, or none of the requested scopes.

3

Issuance

The resulting Access Token contains the granted scopes, which the API must verify before performing an action.

Strategic Design Matrix

How you name and organize your scopes determines the future scalability of your API.

Model	Example	Best For	Trade-off
Resource-Based	photos, contacts	Simple applications with clear data silos.	Hard to differentiate read vs write.
Action-Based	read, write, delete	Internal tools with uniform permissions.	Too broad for sensitive data.
Granular/Namespaced	photos:read, admin:users:invite	Modern APIs & SaaS.	High complexity but maximum security.

Implementation Reference: Scope Validation (Express.js)

// Middleware to enforce required scopes on an endpoint
function requireScope(requiredScope) {
  return (req, res, next) => {
    // 1. Extract scopes from the validated token (e.g., from req.auth)
    const grantedScopes = req.auth?.scope?.split(' ') || [];

    // 2. Perform the proof
    if (!grantedScopes.includes(requiredScope)) {
      return res.status(403).json({
        error: 'insufficient_scope',
        scope: requiredScope
      });
    }

    next();
  };
}

// 3. Apply to protected route
app.post('/api/v1/photos', requireScope('photos:write'), (req, res) => {
  // Logic to save the photo
});

---

Technical Deep-Dives

Explore how scopes interact with modern identity layers and security protocols.

OIDC Scopes

Understanding standard identity scopes: openid, profile, and email.

API Security

Broad authorization patterns for machine-to-machine and user-delegated access.