dummyauth

OAuth guides

OAuth scopes and consent: what to request and why

Learn how OAuth scopes map to permissions and OpenID Connect claims, how consent screens work, and how to request the minimum access your app needs.

6 min read

OAuth scopes are strings your app requests when redirecting the user to authorize. They tell the authorization server what access to grant. Users see them on the consent screen. Requesting too many scopes slows adoption; requesting too few breaks features when tokens lack permissions.

Scopes vs claims

Scopes are requested; claims are returned in tokens or UserInfo. OpenID Connect defines scope-to-claim mappings. For example, the email scope is associated with email and email_verified claims. Custom APIs may use proprietary scopes such as calendar.read that only affect access tokens, not ID tokens.

See OpenID Connect basics for how openid triggers an ID token.

Common OpenID Connect scopes

  • openid — required for OIDC; returns sub and an ID token.
  • profile — name, picture, preferred username (provider-dependent).
  • email — email address and verified flag when supported.
  • offline_access — refresh tokens on some providers (not universal).

Space-separate scopes in the authorize URL: scope=openid profile email. URL-encode the value.

The first time a user sees your client, the server lists requested scopes. Later logins may skip consent if nothing changed. Some providers support incremental auth: request additional scopes in a second authorize call with prompt=consent when you add a feature that needs calendar or repo access.

Copy on the consent screen should match what your privacy policy promises. Test translations and long scope lists on small screens.

Resource-specific scopes

When calling your own API, define scopes that mirror product permissions (billing:read, projects:write). Validate the access token's scope claim (space-separated) in API middleware. Keep OIDC identity scopes separate from API scopes so login libraries do not need to understand your domain model.

Testing scope behavior in dev

On a mock project you can register OAuth clients with different allowed scopes and assert your app handles denied scopes gracefully. Document which scopes each environment needs so CI and staging stay aligned. Related: mock OAuth for development.

Related guides