Your Integration Asked for Every Scope Because Your Docs Never Said Which One It Needed

An enterprise customer's developer builds an integration against your API. It works in their sandbox, the demo goes well, and the project heads to their security team for approval before it can touch production data. Two weeks later it comes back rejected. The reason isn't a vulnerability. The integration asked for every scope your API offers, including write and admin access it never uses, and nobody on either side could explain why.

The developer wasn't being reckless. They opened your authorization docs, found a list of scope names with one-line descriptions, and couldn't tell which ones the four endpoints they needed actually required. So they requested all of them, got a token that worked, and moved on. That's the rational choice when the documentation doesn't answer the question.

The cost lands on you: integrations stalled in security review, deals that slip a quarter, and support tickets that say "403 Forbidden, but my token is valid." For a platform that sells to enterprises, undocumented scopes are an adoption problem disguised as a security setting.

The question your docs leave open

Most API documentation treats authorization as a one-time setup step: register an app, get a client ID, run the OAuth flow, receive a token. That page is usually fine. What's missing is the other direction: given what I'm trying to build, what is the least access I need to ask for?

Your API reference documents each endpoint's parameters and responses. Your auth page lists scopes. The mapping between the two often lives only in your server code, in a middleware decorator or a policy file that nobody outside the platform team has read.

This isn't a new obligation. The OAuth 2.0 specification, RFC 6749, says an authorization server "SHOULD document its scope requirements and default value (if defined)." Plenty of APIs publish a list of scope names and stop there, without saying which operations require which scope.

Why the security reviewer says no

A customer's security team isn't evaluating your API. They're evaluating the access their own developer is asking to grant. When they see a consent screen or a token configuration that requests broad write access for an integration that's supposed to read invoices, they ask the developer to justify each scope. If the developer can't point to your documentation and say "this endpoint needs this scope," the safest answer for the reviewer is no.

Over-scoped tokens also make your customers' incidents worse. A leaked token that could only read reports is an annoyance. A leaked token with admin access is a breach. Security teams know this, which is why least privilege is a standard review question, and why a vague scope list reflects badly on your platform, not just on the integration.

What good scope documentation looks like

GitHub's REST API documentation is a useful model. For fine-grained personal access tokens, it publishes a page that lists, for each permission, the endpoints it unlocks and whether each one needs read or write access, with a column for endpoints that need more than one permission. A developer can work backward from the endpoints they call to the exact permissions they need, and a security reviewer can check the answer.

You don't need GitHub's scale to do the same. Good scope documentation answers these questions:

1. What does each scope allow, in plain terms? Name the data and the actions. "Read invoices and line items for the authorized account" is useful. "Access billing" is not.
2. Which endpoints require which scope? Put it on every endpoint in the reference, and publish the inverse table: each scope and the endpoints it unlocks.
3. Is there a read/write split, and what does write imply? If a write scope also grants read, or an admin scope also grants everything else, say so.
4. What happens when no scope is requested? Document the default, or document that the request is rejected.
5. What does an insufficient-scope error look like? The response should name the missing scope, and the docs should show an example.
6. What's the minimum set for common integrations? A short table of recipes, such as "invoice sync: invoices:read, customers:read," saves every customer from deriving it themselves.

Put the scope next to the endpoint

If your reference is generated from an OpenAPI description, you already have a place for this. Each operation can declare its own security requirement, which overrides the top-level declaration, and for OAuth 2.0 the array lists the scopes the operation requires:

paths:
  /invoices:
    get:
      summary: List invoices
      security:
        - oauth2: [invoices:read]

Many API teams declare one global security block and never declare scopes per operation, so the rendered reference shows a lock icon on every endpoint and says nothing about which key opens it. Filling in per-operation scopes is tedious, but it's mechanical, and once it's in the spec, your reference, your SDK docs, and your inverse scope table can all be generated from one source.

The error side matters just as much. A 403 that says only "Forbidden" sends the developer back to request more scopes, usually all of them. A 403 that says insufficient_scope: requires invoices:write fixes the problem in one step and keeps the token narrow. I made the broader case for treating errors as documentation in Your API's Error Messages Are the Documentation Developers Actually Read.

Audit your scope documentation this week

You can find most of the gaps without outside help:

• Pick five endpoints your customers call most and try to determine, from the public docs alone, which scope each one requires. If you have to open the source code, your customers will too.
• Compare the docs to the code. Find where your server enforces scopes and check that every documented scope matches what's enforced. Scopes that exist in the code but not in the docs, or vice versa, are both bugs.
• Look at real tokens. If you can see what scopes customer integrations request, check how many request everything. That number is a measure of how well your docs answer this question.
• Search support tickets for "403," "forbidden," "permission," and "scope."
• Ask your sales engineers which deals have stalled in customer security review, and what the reviewers asked.

Why this takes an engineer

Scope documentation can't be written from the auth page. Someone has to trace each endpoint through the authorization middleware, confirm what's enforced versus what's intended, notice where a write scope silently implies read, test the failure cases, and then explain all of it so that a developer and a security reviewer reach the same conclusion. That's reading code first and writing second, and it's work I've spent decades preparing for.

If your integrations are stalling in customer security reviews, or your customers keep requesting more access than they need, I can help. I'll map your scopes to your endpoints, document what each one grants, and write the recipes and error guidance that let developers ask for exactly what they need. You can reach me through the contact page.