Understanding Scopes

Learn about application scopes

Scopes define the specific permissions your application is requesting when it accesses an API on behalf of a user or service. Each scope represents a particular level of access — for example, reading user profile data, sending email, or making a LLM request.

When a user authorizes your application, they are shown a consent screen listing the scopes your app has requested. This allows users to make an informed decision about what data or actions they’re granting access to.

How Scopes Work

• Scopes are included in the OAuth authorization request (e.g., scope=account user-data).

• The authorization server validates these scopes and issues an access token returned to your service with the granted scopes.

• The API then checks the token to determine what actions the client is permitted to perform.

• Tokens can only be used to access resources that correspond to the approved scopes.

Selecting the Right Scopes for Your Application

When creating or editing your Client ID, you’ll have the option to specify which scopes your application wants to use. Here are best practices for choosing your application scopes:

• Request only what you need — excessive scopes may trigger user distrust or require additional review.

• Review and update scopes periodically as your app’s permissions evolve.

• Test your app with the minimum viable scope set to ensure functionality.

Modifying the scopes of your application/client does not automatically update the existing authorization tokens of your users. You will need to redirect your users to re-authorize your application to obtain new tokens with the updated scopes.

You can view the complete list of available scopes, along with detailed descriptions, on our Scopes Reference page.