Skip to main content

​
What are Scopes?

Scopes are a mechanism in OAuth 2.0 and OpenID Connect that define the level of access that an application is requesting from a user. They allow users to grant limited access to their resources without sharing their credentials.

​
OpenID Connect Scopes

ScopeClaims
openid(required) Returns the sub claim, which uniquely identifies the user. In an ID Token, iss, aud, exp, iat, and at_hash claims will also be present.
profileReturns claims that represent basic profile information, including name, family_name, given_name, middle_name, nickname, picture, and updated_at.
emailReturns the email claim, which contains the user’s email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
offline_accessReturns a refresh_token.

​
openid

The openid scope is required for all OpenID Connect authentication requests. It indicates that the application wants to use the OpenID Connect protocol to verify the user’s identity.
  • Required: Yes (for OpenID Connect flows)
  • Returns: An ID token containing the user’s unique identifier (sub claim)
  • Example: scope=openid
Without this scope, the request is treated as a plain OAuth 2.0 authorization request rather than an OpenID Connect authentication request.

​
profile

The profile scope requests access to the user’s default profile information. When granted, it allows the application to access basic profile claims.
  • Required: No
  • Returns: Claims such as:
    • name - Full name
    • family_name - Last name
    • given_name - First name
    • middle_name - Middle name
    • nickname - Casual name
    • preferred_username - Preferred username
    • profile - Profile page URL
    • picture - Profile picture URL
    • website - Web page or blog URL
    • gender - Gender
    • birthdate - Birthday
    • zoneinfo - Time zone
    • locale - Locale
    • updated_at - Time profile was last updated
Example: scope=openid profile

​
email

The email scope requests access to the user’s email address information.
  • Required: No
  • Returns: Claims such as:
    • email - Email address
    • email_verified - Boolean indicating whether the email has been verified
Example: scope=openid email This scope is commonly used when applications need to communicate with users via email or use email as a unique identifier.

​
offline_access

The offline_access scope requests permission to access resources on behalf of the user even when they are not actively using the application.
  • Required: No (but required for refresh tokens)
  • Returns: A refresh token that can be used to obtain new access tokens
  • Duration: Long-lived or indefinite, depending on the authorization server’s configuration
Example: scope=openid offline_access This scope is essential for applications that need to:
  • Perform background synchronization
  • Access resources without requiring the user to re-authenticate
  • Maintain long-term access to user data
Not all grant types support refresh tokens. The offline_access scope typically works with the Authorization Code flow and may not be available for Client Credentials or other flows.

​
Additional Scopes

​
phone

The phone scope requests access to the user’s phone number information.
  • Required: No
  • Returns: Claims such as:
    • phone_number - Phone number
    • phone_number_verified - Boolean indicating whether the phone number has been verified
Example: scope=openid phone

​
address

The address scope requests access to the user’s postal address information.
  • Required: No
  • Returns: A JSON object containing:
    • formatted - Full mailing address
    • street_address - Street address
    • locality - City or locality
    • region - State, province, or region
    • postal_code - Zip code or postal code
    • country - Country name
Example: scope=openid address

​
Combining Scopes

Multiple scopes can be requested in a single authorization request by separating them with spaces: 
scope=openid profile email offline_access
This request would:
  1. Use OpenID Connect authentication (openid)
  2. Request access to profile information (profile)
  3. Request access to email address (email)
  4. Request a refresh token for offline access (offline_access)

​
Best Practices

Only request the scopes your application actually needs. Requesting excessive permissions may reduce user trust and decrease authorization approval rates.
  1. Principle of Least Privilege: Request only the minimum scopes required for your application’s functionality
  2. Transparent Communication: Clearly explain to users why your application needs specific scopes
  3. Progressive Authorization: Request additional scopes only when needed, rather than all at once
  4. Secure Storage: Store tokens securely, especially refresh tokens obtained through offline_access
When an application requests scopes, users are typically presented with a consent screen showing:
  • What application is requesting access
  • What specific permissions (scopes) are being requested
  • What data will be accessible to the application
Users can choose to:
  • Approve: Grant the requested scopes to the application
  • Deny: Refuse the authorization request
  • Partial Approval (if supported): Grant only some of the requested scopes