HubSpot OAuth FAQ

[Derek_Gervais]

This short guide is intended to address some of the most common OAuth-related questions. While it is by no means comprehensive, it should help illuminate some topics that commonly cause confusion.

User/Account/App Permissions

• Users have roles, which are related to the permissions they have within a particular HubSpot account. Some users can access the blog tool, while others can only access the CRM. Some users are admins, and still others might be super admins. These user roles affect whether or not a specific user can authorize a given app.
• Accounts have access to different tools based on their product tier, add-ons, and included hubs. Some accounts are Marketing/CRM Free, some are Marketing Hub Enterprise & Sales Hub Professional, and some may have the Website add-on. These tools affect whether or not a specific account can connect a given app.
• Apps request certain scopes when initiating an OAuth2 connection. Your app may request content, contacts, and timeline, for example. All scopes can be either required or optional, but only the required scopes affect whether or not an app can be connected to a given account. These scopes determine whether or not a specific user can connect the app to a specific account.

Let’s consider a hypothetical app that only requires the hubdb scope. What conditions must be met in order to connect this app?

• The account in question must have access to the tools that correspond to the required scopes the app is requesting.
• In our example, the app is requesting the hubdb scope. This means that the account in question must include the HubDB tool.
• The user who is authorizing the app must have the roles required to authorize the required scopes the app is requesting.
• In our example, the app is requesting the hubdb scope. This means that the user must have full access to the HubDB tool.

Whether or not an app can be installed depends on the intersection of the app's required scopes, the account’s included tools, and the authorizing user's roles. This is what makes troubleshooting these issues so situation-specific; slight differences in user roles, account tiers, or required scopes can be factors in why a particular user/account/app combination isn't working as expected.

Apps are Account-wide

Another important thing to consider here is that under the current HubSpot OAuth implementation, apps are always installed account-wide. This means that a single user authorizes an app, and that app then has access to the entire account.

Conceptually, the OAuth2 flow is more like installing a program to your computer than signing into an account. For example, when installing Microsoft Word, an admin with the proper permission installs the program to the device. The program can then be used by all users on the computer. Similarly, one user (usually an admin) needs to authorize an app’s connection to HubSpot. After that, the app provides some functionality to the account that can be used by all. (e.g. adding contact properties, creating timeline events, etc.)

It's not currently possible to create user-specific apps using the HubSpot APIs, so ideally there shouldn't be situations where more than one user needs to complete the OAuth2 flow for a single account. If multiple users need to authorize your integration, then every user must meet the criteria above.

Common Errors

See here:

• This hub doesn't have access to some HubSpot features that are required by this app. Please contact the integrator
  • This error means there is an issue with the account. The account being selected does not include the tools that correspond to the required scopes the app is requesting. This is often related to subscription level.

• You do not have the correct role to grant these permissions. Please contact your administrator
  • This error means there is an issue with the user. The user attempting to authorize the app does not have the roles required to authorize the required scopes the app is requesting.

When in doubt, have a super admin try to install the app. A super admin should always have the proper role to approve any app. The one exception here are apps that require the ecommerce scope; because this scope includes permissions related to being a Sales Hub Professional user, installing an app that requests the ecommerce scope must be done by a Sales Hub Professional user.

Getting Help

HubSpot Support is equipped to help you with authorization issues. In general, Support will need the account's Hub ID, the user's email address, and the app's required scopes in order to effectively troubleshoot OAuth 2 issues.