What are OAuth scopes?

Scopes (OAuth scopes), explained#

In OAuth, scope is a space-separated list of strings sent with the authorization request. The strings themselves are defined by each API, not by the standard. Common patterns are resource.action, like calendar.read, or a resource with a colon, like repo:status. The authorization server may grant fewer scopes than requested, and the token response says which were granted.

Scopes describe what the app may ask for on the person's behalf. They are not the same as the person's own permissions. A careful API checks both on every request: does the token hold the scope, and is the person behind it allowed to do this thing to this record? A scope should only ever narrow what the person can do, never add to it.

Good scope design follows least privilege. Separate read from write, keep sensitive data in its own scope, and avoid one scope that implies all the others. When a client needs more later, it can ask again for a wider set rather than requesting everything up front. The MCP specification calls this incremental approach step-up authorization.

When a token lacks a scope, the standard response (RFC 6750) is 403 with WWW-Authenticate: Bearer error="insufficient_scope" and a scope parameter naming what is needed.

For example, a reporting tool asks for projects.read and work.read. Its token can list projects and issues but cannot create one, and if its owner cannot see a private project, the token cannot either. When a teammate later wants it to file issues, the tool asks for work.write and the person approves that one addition.