Scopes provide access to a specific set of HubSpot API endpoints and the associated data from a HubSpot account.Documentation Index
Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
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 theauth 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
scopequery 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
scopequery 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
scopequery parameter for users with access to a feature, while another install URL omits that scope in thescopequery 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.
- 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
- Optional scopes: scopes that are not required to successfully install your app. These scopes are specified in the
optional_scopequery 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 thecrm.objects.custom.readscope 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.Deprecated scopes
The following scopes are associated with deprecated APIs and should not be used for new app development:accountingactionse-commerceintegration-syncsocial