Apr 2, 2019 11:36 AM
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.
Let’s consider a hypothetical app that only requires the hubdb scope. What conditions must be met in order to connect this app?
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.
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.
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.
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.