A scope is a named permission attached to a token. invoices.read. payments.write. The token carries
the scopes the user granted, and your API enforces them per operation.
Design them at the granularity a consumer actually reasons about. Too coarse — one api scope that
grants everything — and consent becomes meaningless and every integration is over-privileged. Too fine
— a scope per endpoint — and the consent screen turns into a wall of checkboxes nobody reads, which is
just a different way of making consent meaningless. Resource-plus-action is usually the right level.
Then treat scopes as documentation, not configuration. Publish a scopes page listing every scope, what it grants, and which operations require it. Reference the required scope inline next to each operation in the reference documentation, and declare them in your OpenAPI security schemes so tooling can pick them up. Consumers should never have to guess which scope an operation needs, and they do this by trial and error at most providers.
One thing worth appreciating: the scope is where the terms of a relationship actually get expressed. When a bank, a health system, or a government agency negotiates what a partner may reach, that negotiation ends up encoded as scopes. It is a small technical construct carrying a large amount of policy.
