OAuth 2.0 Scopes

Scopes decompose monolithic access into discrete, string-based permissions. Each scope represents a specific action on a protected resource.

• Format: Case-sensitive strings, often structured as resource:action (e.g., drive:read, profile:email)
• Atomicity: A single scope should grant one specific capability, not a bundle
• Composability: Clients request multiple scopes in a single authorization request using space-delimited lists

Example: A photo printing service might request photos:read and storage:write—allowing it to download images and save prints, but not delete originals.

OAuth 2.0 supports both statically defined and dynamically generated scopes, offering flexibility for complex authorization models.

• Static Scopes: Pre-registered with the authorization server. Predictable and auditable (e.g., openid, profile)
• Dynamic Scopes: Registered at runtime by the resource server, often parameterized. Useful for fine-grained, resource-specific permissions
• Pattern: resource:operation:resource-id (e.g., document:edit:doc-123)

Dynamic scopes enable attribute-based access control (ABAC) patterns within the OAuth framework, allowing permissions to target specific objects.

The authorization server is the Policy Decision Point (PDP) for scope issuance. It validates that the requested scopes are appropriate for the client and user.

• Client Registration: Scopes must be pre-approved for a client's identity
• User Consent: The resource owner must explicitly approve the requested scopes
• Token Introspection: Resource servers (PEPs) call the introspection endpoint to verify the token's scopes before serving data

Security Trimming: If a token lacks the admin:read scope, the resource server must filter out administrative fields from the response, enforcing field-level security.

Well-designed scopes are critical for security and usability. Poor scope design leads to over-privileged clients and confused users.

• Least Privilege: Define the smallest possible unit of access. Avoid catch-all scopes like /api/*
• Clear Naming: Use intuitive, hierarchical namespaces (read:public vs read:private)
• Consent Optimization: Minimize the number of scopes requested to reduce consent friction
• Incremental Authorization: Request additional scopes later in the user journey via a re-authorization prompt

Anti-pattern: A single admin scope that grants read, write, and delete privileges violates the principle of least privilege.

In Answer Engine Architecture, OAuth scopes enforce document-level security during retrieval. The RAG pipeline uses the user's access token to perform pre-retrieval filtering.

• The query engine extracts scopes from the user's JWT
• A security trimming filter is applied to the vector database query, excluding chunks from unauthorized documents
• This prevents data leakage by ensuring the language model never sees restricted content

This mechanism is a core component of Retrieval-Augmented Generation Authorization, binding AI-generated answers to the user's real-time permissions.

Standard scopes for identity and authentication, defined by the OpenID Connect specification.

• openid: Mandatory scope to initiate an authentication request. Returns an ID Token.
• profile: Requests access to the user's default profile claims (name, picture, locale).
• email: Requests access to the email and email_verified claims.
• address: Requests access to the user's physical address claim.
• phone: Requests access to the phone_number and phone_number_verified claims.

Google uses highly granular, URL-formatted scopes for its extensive API ecosystem.

• Read-only Calendar: https://www.googleapis.com/auth/calendar.readonly allows viewing events without modification rights.
• Gmail Send: https://www.googleapis.com/auth/gmail.send grants permission to send emails only, not read the inbox.
• Drive File Access: https://www.googleapis.com/auth/drive.file restricts access to only files created or opened by the application, preventing broad data exposure.

GitHub scopes control access to repositories, user data, and administrative functions.

• repo: Grants full control of private and public repositories, including code and settings.
• repo:status: Grants read/write access to commit statuses only, a minimal scope for CI/CD pipelines.
• read:org: Allows reading the user's organization memberships without exposing repository data.
• delete_repo: A highly privileged scope granting the ability to permanently delete repositories.

Microsoft Graph uses a resource.operation.constraint format for fine-grained access to Microsoft 365 data.

• User.Read: Allows a user to sign in and read their own basic profile.
• Mail.ReadWrite: Grants the ability to read, create, and update a user's mail.
• Files.ReadWrite.All: Grants access to all files a user can access, a broad scope requiring admin consent.
• offline_access: Requests a refresh token, allowing the app to access data when the user is not present.

Slack scopes define what a bot or app can do within a workspace, often separated by service.

• chat:write: Allows the bot to send messages as itself.
• channels:history: Grants access to view messages and other content in public channels.
• commands: Allows the app to register custom slash commands.
• users:read.email: Permits viewing the email addresses of users in the workspace, a sensitive scope.

Organizations define custom scopes for internal microservices and APIs to enforce fine-grained authorization.

• documents:search: Allows a retrieval-augmented generation (RAG) system to query a vector database without read access to full documents.
• transactions:void: A specific scope for a payment service that allows canceling a transaction but not initiating a new one.
• reports:export.financial: A compound scope that grants access to a specific report type, limiting lateral movement.