Scopes: Least Privilege as Contract Surface

A scope is a cap on the *credential*, not a grant to the *user*. When a CI integration holds a token scoped to projects:read, the API will refuse that token a billing read even though the human who authorized it is the org owner who could see billing in the dashboard. That is the point: effective access is the intersection of what the user may do and what the token was scoped to ask. Scopes exist because credentials leak, get logged, and sit in third-party databases — the scope decides what the thief gets.

This makes scopes a different axis from Authorization Design in the Contract, and you need both. Scope answers "may this *application* ask for this category of operation?" — checked first, cheap, no data required. User permission answers "may this *person* touch this *object*?" — checked second, against the data. A token with projects:write still cannot edit a project its user is not a member of; a project admin's token without projects:write cannot edit anything. Collapsing the two axes — treating a scope as if it granted access, or skipping object checks because "the scope covers it" — recreates Broken Access Control (IDOR / BOLA) with extra steps.

One giant scope is the common failure: the API offers api:full (or every integration requests admin because that is what the tutorial showed), and now the read-only Slack notifier holds a credential that can delete the org. When it leaks — and integrations' credentials leak, from *their* infrastructure, outside your control — the blast radius is everything. Users learn nothing from the consent screen ("this app wants: full access"), so consent stops being informed, and your audit team cannot distinguish the integration that could have exfiltrated billing data from the one that could not.

The opposite failure is quieter: per-endpoint or per-field scopes (projects.name:read, projects.members.email:read) produce a catalog of hundreds, consent screens with twelve checkboxes nobody reads, and developers who cannot predict which scope tomorrow's endpoint will need — so they request everything available, defeating the purpose with the opposite mechanism. The workable middle for most APIs: resource-family × read/write, single digits to a few dozen scopes, with read never implying write and genuinely dangerous capabilities (org deletion, member removal, secret access) carved into their own explicitly-named scopes so the consent screen says something a human can weigh.

Scopes appear in the contract at three moments. At request time, the consumer names them (the OAuth scope parameter — the flow itself is OAuth 2.x — Delegated Authorization territory; the *catalog* being requested is yours). At response time, the token comes back with the scopes actually granted, which may be fewer — contracts that let users deselect scopes must say so, and consumers must read the granted list instead of assuming. At failure time, a call outside the token's scope returns 403 with error.code: "insufficient_scope" and — the clause developers thank you for — *which scope was missing*, so the fix is a re-consent with the named scope rather than an afternoon of probing. Keep this failure distinct from 401 (credential broken, see Authentication in the Contract) and from permission denials: three different recoveries, three different error identities.

The catalog evolves under compatibility rules like any contract surface. Adding a scope for a new resource family is additive and routine — new endpoints require it, existing tokens that lack it get the documented insufficient_scope failure, and integrations opt in by re-requesting consent. What you cannot do quietly: retroactively *broaden* what an existing scope covers (tokens in the wild silently gain power — a security regression executed by documentation), or *narrow* one (integrations break mid-flight). Both are real changes to deployed credentials; narrow with a deprecation program, broaden never — mint a new scope instead.