OAuth inconsistency in scope permissions for users


So, it doesn't happen often but every once in a while, we will get a user attempting to authenticate for the first time to our app. They are administrators who have read, write access to all the scope our app requires: "forms, contacts, content, files". I have even created a secondary user and matched their permissions 1-1 to the account that can't gain access and it works fine.
I wish I had debugging info to provide to help work through this issue but the permissions die on the HubSpot hosted page level. I can't get a return to my app to try and debug and the error screen provided by HubSpot doesn't notify the user into which scope they don't have the proper access to.

  1. has anyone out there ran into this same issue
  2. How do I resolve it
  3. How do I get better error reporting if the round trip for the OAuth never gets back to my servers
  4. Is there some kind of flag I can send to the HubSpot Auth page that will give the user more information on why they can't connect?

Here's what users are seeing when they run into this issue.

Here'sanother post that appears to be similar to the issue I'm seeing

Thank you for the help

Hubspot OAuth integration requires admin approval but user is already an admin

Hi @Tim_Joyce_Belch,

These issues are pretty tricky, since a successful authentication occurs only with the correct intersection of requested scopes, portal tools, and user permissions. I wrote up a wiki-style reply on this that I'll share at the bottom of the post. The tl;dr is that they often have to be addressed on a case-by-case basis, since this error is often expected (and necessary to avoid users authorizing integrations that they shouldn't be).

The simplest way to avoid this in all situations is to make sure that the user authorizing the integration is a super admin. If a portal has all the required tools, a super admin will always be able to approve the integration. If that's not possible for one reason or another, then the following post has details on what to include in a request to get help with these errors:


Thanks for the details on the OAuth2 @Derek_Gervais.
So, If a user does have all the correct permissions on the scopes but still has issues logging in... They should ask a super admin to login, which will approve the app to be installed in the portal? Then the basic administrator with correct scope privileges can complete the login without failure and continue to use our integration? Or am I over-simplifying the process?


Hi @Tim_Joyce_Belch,

It's best to think of this process as an installation to a portal. The HubSpot OAuth flow is conceptually similar to installing a program on your computer; when you install software on your computer, you need to have the correct user permissions and your computer must meet the minimum requirements. If all those criteria are met, you'll successfully install the application and going forward all users of that computer will have access to the program's functionality. If you are not an administrator (i.e. you don't have the correct permissions) you'll need to get an administrator to install the program to your computer so that you can use it. You don't necessarily need to be authorized to install the program in order to use it; the program works for all users after it's installed.

Similarly, when you install an integration to your portal, you must have the correct permissions and your portal must have access to the required scopes. If all those criteria are met, you'll successfully install the integration and going forward all users in your portal will have access to the integration's functionality. If you don't have the correct permissions, you'll need to get an administrator to install the integration to your portal so that you can use it. You don't necessarily need to be authorized to install the integration in order to use it; the integration works for all users after it's installed.

Knowing that, the surest way for a user to complete an installation where a particular user doesn't have the required permissions is to get another user in their portal with the proper permissions (preferably a super admin)to install it for them.


Hi @Derek_Gervais - Thanks for your response.
So, I just did a test to validate your response and it failed.

User A (super admin) has already authorized my integration to the portal
Then, added User B to the portal
Then, tried to login to the integration with User B and permission was denied.
Permission continues to be denied until I make them a Super Admin.

Can you please explain why that is?

Also, I'm not trying to be rude but, is there a better way to have this communication with you? 7 days between responses is not ideal, as you could imagine.

Thanks again


Hi @Tim_Joyce_Belch,

I totally understand that having such long delays isn't an ideal service experience. Unfortunately, right now I'm the only person available so my time is split between all the topics of the forum (as well as various other Developer Advocacy responsibilities). I also went on vacation a couple weeks ago, which lead to a fairly large backlog here in the forums. We should be returning to normal later this week, where I can get back to everyone within a few days. The good news is we're taking steps internally to scale up our developer support capabilities; stay tuned for more updates on that in the near future.

Anyway, back to your question; once the super admin authorizes the integration, you should not be completing the auth flow with a separate user. The auth flow only needs to occur once; after that, your app can make requests to the HubSpot API for that portal. The various other users in the portal can then take advantage of whatever functionality your app adds to the portal.

Maybe it would help me better understand your issue if I knew more about what your integration is doing; why do multiple distinct users need to authorize your integration for a single portal?


Thanks for your respons @Derek_Gervais and I can totally understand time splits and vacations. Is there any way we can communicate through email or a quick conference call? I would really like to give you a first hand look into the integration app since it has a lot of moving parts that integrate with the API in ways that (I don't believe) others have integrated. We've also developed our customer subscription plan process in a unique way.