Skip to main content
Scopes provide access to a specific set of HubSpot API endpoints and the associated data from a HubSpot account.

​
Find required scopes for an endpoint

Any scopes required to make a request to a specific endpoint will be listed under the Required Scopes section in a reference article or the expandable Scope requirements section of the corresponding API guide. These API resources can be accessed by navigating to the APIs section of HubSpot’s developer documentation, then drilling down into the specific API you need (e.g., the contacts API guide).

​
App scope types

When you specify the scopes within the auth property of your app-hsmeta.json configuration file, there are three different scope types available for you to configure. You must specify the scopes your app will require for installation, but you can also specify two other scope types: conditionally required scopes and optional scopes.
  • Required scopes: scopes that must be authorized by the user and must be present in the scope query parameter in your app’s install URL for successful installation.
  • Conditionally required scopes: scopes that must be authorized by the user only if they’re present in the scope query parameter in your app’s install URL for successful installation.
    • This scope type allows you to be flexible and provide a separate install URL for tiered features or scopes that are only required when users enable certain features in your app. For example, you could offer two install URLs to your users: one install URL could include the conditionally required scope in the scope query parameter for users with access to a feature, while another install URL omits that scope in the scope query parameter for users without access.
    • If a conditionally required scope is present in your app install URL and a user without access to the associated feature attempts to install your app using that URL, the installation will fail.
  • Optional scopes: scopes that are not required to successfully install your app. These scopes are specified in the optional_scope query parameter in your app’s install URL. For example, if you want your app to be able to fetch custom object data (which is only available to Enterprise HubSpot accounts), you could add the crm.objects.custom.read scope as an optional scope. Then, if an account has access to the custom objects, the scope will be authorized. Otherwise, they’ll still be able to install the app without the custom objects scope.

​
List of available scopes

Access to specific APIs or endpoints depends on HubSpot account tier. You can find a full list of available scopes and accessible endpoints in the table below.
Please note: the scopes listed below may appear on certain app configuration pages but do not currently have a corresponding API available:
  • cms.knowledge_base.articles.write
  • cms.knowledge_base.articles.publish
  • cms.knowledge_base.settings.read
  • cms.knowledge_base.settings.write
  • ctas.read

​
Deprecated scopes

The following scopes are associated with deprecated APIs and should not be used for new app development:
  • accounting
  • actions
  • e-commerce
  • integration-sync
  • social
Last modified on March 6, 2026