A developer platform issues OAuth tokens to third-party applications. What scope design decisions determine whether the platform can be operated safely long term?

The decisions that matter

1. Scope granularity, chosen before launch. Scopes that are too coarse mean every integration requests broad access, so a compromised integration is catastrophic. Too fine and the consent screen is incomprehensible, users approve without reading, and the granularity buys nothing.

The workable shape is resource plus action (repo:read, issues:write) with a small number of high-privilege scopes clearly marked. Crucially, scope design is effectively permanent — splitting a coarse scope later breaks every integration that requested it.

2. Resource-scoped installation rather than user-scoped tokens. A token acting as a user has all that user's access, everywhere, forever. A token scoped to specific resources — selected repositories, a specific workspace — bounds the blast radius to what the integration actually needs. This is the single most important structural decision, and platforms that start user-scoped find it very hard to move.

3. Short-lived tokens with refresh. Long-lived tokens are the assets that appear in breach reports. Short expiry with rotation means a leaked token has a bounded window, and it forces the refresh path to work — which is what makes revocation meaningful.

4. Revocation that is immediate and complete. Revoking must invalidate tokens everywhere at once, which means either short-lived tokens or a revocation check on the hot path. A revocation that takes effect at next expiry is not revocation.

5. Consent that is honest and re-confirmed. The user must see what they are granting, in their terms, and be asked again when an integration expands its scopes. Silent scope expansion is the mechanism by which an integration accumulates access nobody agreed to.

The operational half that platforms underestimate

• Token usage telemetry per integration, so anomalous behaviour — a sudden change in access pattern — is detectable, and so scope usage can be measured. Measured usage is what makes it possible to reduce an integration's scopes.
• A path for users and administrators to see and revoke every integration's access, in one place.
• Secret scanning for leaked tokens, with automatic revocation. Tokens end up in public repositories routinely, and detecting that is far more effective than asking developers to be careful.
• Rate limits per integration, since a compromised or buggy integration is also an availability threat.

The lesson

Scope design is an API design problem with a security consequence and no version-two. The permission model granted to thousands of integrations cannot be tightened later without breaking them, which is why it deserves more design attention than almost anything else on a developer platform — and why the default should be narrower than feels convenient at launch.