OAuth contact permission flow



I read over this topic:

And it seems like

  1. Super admin enables integration for the portal
  2. Users authenticate as usual (they do not have to have super admin permissions to enable the integration)

I built an integration that requests the 'contacts' scope and some users ran into this error: "You do not have the correct role to grant these permissions"

Does that mean the super admin didn't enable the integration yet?

Assuming the super admin did enable the integration, when the normal end user tries to use the integration, does the end user need all permissions enabled (e.g. Read/write access, workflows, etc) for the contact scope to be valid?
Or is there any way for us to request the contact scope, but if the user does not need to have all permissions for the "Contact" role enabled?

Additionally, is there any way to check in HubSpot which incoming integrations have been enabled?

Thanks in advance for your help!!


Hi @kschiu,

That's not exactly how the auth process works. Installing an integration to a HubSpot portal is conceptually very similar to installing a program to your computer; once it's installed, it's available for all users of that computer. An admin may be required to install it, but after that users can use it without installing it again.

For a specific example, let's say I create an integration that requests the contacts scope and updates contact properties with important information from my external system. In order to use my integration, a user with the proper permissions would need to complete the installation flow. After they install my integration, no other users should complete the installation flow. My integration is now free to update contact properties for any contact, and all users in that portal can take advantage of it's functionality. There isn't currently any concept of user-level integrations with HubSpot; integrations are all portal-wide.



When you say No other users should complete the installation flow, how are vanilla users supposed to use the installed integration?

The issue I'm running into is that the application is enabled for the portal by a super-admin and now we want to allow individual non super-admins to use the integration with their own login credentials. We currently hit the oauth/authorize endpoint for all users, which sounds like it means we're trying to (incorrectly) do the installation flow for all users?

Is that possible to enable an integration for the whole portal and then allow all users to login with their own credentials to use the application with the OAuth2 flow? Or is the OAuth2 flow meant only for installing applications for the HubSpot portal?

Please let me know if that makes sense or if you need more specific info.


Hi @kschiu,

That does make sense; you're correct when you say that the OAuth2 flow is intended to install an integration to a portal. It's not intended to be a user-level login/authorization flow. Here's an example of the 'expected' flow, which I think will help clarify things:

Imagine I've created an integration between my app and HubSpot. For this example, imagine my app allows companies to upload cool images to their page, and also allows users to browse the images, 'like' their favorite ones, and even purchase prints. In this example, my integration would allow a company to integrate their account in my app with their HubSpot account. My integration with HubSpot might do any number of the following things:

  • Create custom timeline events anytime a user 'liked' one of my pictures in my app
  • Add a number of custom contact properties that stored information from my app (e.g. number of pictures 'liked', favorite picture category, etc.)
  • Add a CRM Extension with various profile information and links to the contact's profile in my app
  • Create a deal in HubSpot whenever a user purchases a print in my app

The important takeaway from this example is that each and every one of these features is a portal wide feature; if one single HubSpot user approves my integration, my app can now use the Timeline API, Contacts API, CRM Extensions API, and Deals API to do all of these things without any further intervention from other HubSpot users.

Because of this, any other HubSpot user that is working in the portal has access to any of these features, assuming they have access to the relevant HubSpot tool. If they have access to view a contact record, they can see the timeline events that appear on that contact's timeline. If they have access to view deals, they can see the deals created by my integration, and so on and so forth.

Without knowing exactly what your integration is doing, it's tough to say for sure what functionality from your app a 'typical' HubSpot user would have access to. I'd be happy to discuss that if you wanted to give some more details on the integration, though.

Mixed results having users log in with the 'contacts' scope
Hubspot OAuth integration requires admin approval but user is already an admin


Okay I see, so is there any mechanism for user-level login once an application has already been installed on the HubSpot portal?

Our application wants to allow individual users (logged in as themselves) to edit contacts, deals, engagements, after a super-admin has enabled the integration for the portal.

The flow is:
In our application, super-user logs into Hubspot (via our application) via OAuth2.
Now that the application is enabled for the portal, in our application, allow normal users to log in with their own credentials and perform CRUD operations on contact, deal, engagements.

We would like all login and basic CRUD operations to be done in our application and then our application makes the requests to HubSpot's APIs.

Please let me know if there's a user-level login/authorization flow and if not, if there's a workaround for how users (with normal privileges) can be authenticated as themselves once our application is enabled for the HubSpot portal

As always, thanks for your help!


Hi @kschiu,

There isn't currently any form of user-level authentication for HubSpot integrations, though that's something the team has considered and may decide to work on in the future. That said, I don't believe you require that for the situation you're describing.

Once the OAuth flow has been successfully completed by the super user, the resulting access/refresh tokens allow your app to have full access to all contacts/deals/engagements/etc. You don't necessarily need your users to log in or in any way 'connect' with HubSpot at the user-level. Instead, a user with sufficient permissions in your app can make changes to records, and then your app can send those changes to the corresponding record in HubSpot. If the users are authenticated in your app, and they should be allowed to make changes that affect data in HubSpot, you can simply make those changes (authenticated with the access token obtained from the initial auth flow).

Does that make sense? Let me know if I can help clarify anything or answer any other questions.