OAuth2 Scopes
You set up oauth2 scopes by defining permission strings in your identity server. Then you require client apps to request those strings during the login flow. Most teams group these strings by role, such as read or write. When teams make these strings too broad, a single token grants far too much power. One stolen token can let an app or user change data across many systems. How oauth2 scopes work in the login flow A scope is a plain text label that limits what an access token can do. First, a
Scopes: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up oauth2 scopes by defining permission strings in your identity server. Then you require client apps to request those strings during the login flow. Most teams group these strings by role, such as read or write. When teams make these strings too broad, a single token grants far too much power. One stolen token can let an app or user change data across many systems.
How oauth2 scopes work in the login flow
A scope is a plain text label that limits what an access token can do. First, an admin creates scope labels inside the central identity server. Each label maps to a broad action, like reading user profiles or writing billing records. Next, a person or app starts a login flow and asks for specific labels.
The identity server checks the user role and policy rules before it approves the request. In some flows, the user also sees a consent screen and approves the requested labels. After approval, the identity server mints a signed token that lists the granted labels. The client app sends this signed token along with every API call it makes.
The receiving service checks the token signature and reads the scope claim inside it. If the required label is missing, the service blocks the request right away. If the label is present, the service runs the action and returns the result.
How teams design scope labels for services
Good scope design separates read actions from write and admin actions. Teams often pair a resource name with an action verb to keep labels clear. For example, a label might cover reading orders or updating customer records. Service owners map each API route to one or more required labels.
Problems start when a team adds dozens of databases, internal tools, and cloud services. Managing hundreds of tiny scope labels across every identity group gets messy fast. To save time, admins often fall back to coarse labels like full read or admin. A developer who needs to check one production table gets a broad write scope instead. That token stays valid until it expires, even after the developer finishes the task.
Scopes: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What scopes solve and what they leave open
Scopes do a great job of limiting which endpoints an app can call. They stop a read-only reporting app from calling a user deletion route. They also let identity teams see which high-level permissions an app asked to use. This works well for standard web APIs with simple, fixed routes.
Still, oauth2 scopes only check permission at the door before a session or request runs. They do not inspect the actual database query, shell command, or payload inside the session. A token with a database read scope can still pull a whole table of emails. That same read scope cannot mask phone numbers, card numbers, or national IDs in results.
A token with a write scope can drop a table or update ten thousand rows. The identity server never sees the SQL statement or CLI command that the user runs. Once the token passes the initial scope check, every command inside that scope runs unchecked. Teams still need a way to inspect commands and mask sensitive fields in flight.
Govern statements and responses across databases and APIs
Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev sits inline in the protocol beside each supported service as an open-source proxy, a sidecar for your database or API. For every query or command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human approval.
First, hoop.dev guardrails block banned queries before they run or hold risky ones for review, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
What is the difference between a role and a scope?
A role belongs to a user and defines what that person can do. A scope belongs to a token and limits what a client app can do on their behalf.
Can oauth2 scopes block a dangerous SQL query?
No, scopes only check if a token has general read or write permission. They do not parse SQL text or block a drop table command inside a write session.
How often should teams review their token scopes?
Teams should review scope assignments every quarter and whenever a service adds new endpoints. Regular checks help remove broad admin labels that developers no longer need for daily work.