Optional Scopes and "You do not have the correct role to grant these permissions."



Hello, I’m attempting to verify that my company’s HubSpot OAuth2 app can be integrated with our clients’ HubSpot accounts. I understand that CRM-only HubSpot accounts do not have access to scopes that are only available to Marketing HubSpot accounts.

I have no problem authorizing with the Test Portal that’s set up alongside our Dev Account. However, I’m not able to authorize our app when using a dummy HubSpot account (Hub Portal ID: 3306102) with these products: HubSpot Marketing Free, HubSpot CRM, and HubSpot Sales Free. Specifically, I get this error:

Uh oh!
You do not have the correct role to grant these permissions. Please contact your administrator.

The HubSpot OAuth API documentation denotes the optional_scope parameter which has this description:

Optional scopes will be automatically dropped from the authorization request if the user selects a HubSpot account that does not have access to that tool (such as requesting the social scope on a CRM only portal).

Our app does request permission for Marketing-only scopes, namely “content”, “reports”, “automation”, and “forms”. I added those scopes to the optional_scope param as per the documentation.

The resultant OAuth URL looks like this:


Attempting to initiate OAuth access using this URL with the optional_scope param also results in the permissions error I noted above.

I attempted to make all the scopes optional:


But again, this results in the same error.

I’ve found similar issues, one of which has a note saying it was resolved:

Am I misunderstanding the purpose of optional scopes? Any insight into this error would be appreciated. Thanks in advance!



Are you an admin in the portal you are trying to install the app into?
Also both the URLs have all of the scopes required in addition to be optional.


They should be in one group. optional or not.


Thanks for the response @pmanca.

I believe I am an admin in the portal I’m trying to install the app into. In my user preferences page it says “Marketing Administrator”, “Sales Administrator”, and “Account Administrator”.

They should be in one group. optional or not.

Do you mean each scope should be in one group or the other? The “contacts” scope appears to be permissible for Marketing and/or CRM accounts, and the other scopes are Marketing-only.

My new URL looks like this:


Doing this results in a different error:

Uh oh!
Insufficient scopes were provided. Please contact the integrator.

The application I’m trying to integrate with has the following scopes:

Read from and write to my Contacts
Read from and write to my Content
Read from and write to my Reports
Read from and write to my Workflows
Read from and write to my Forms

I cannot find my application id for my main domain (DO NOT RUSH TO ANSWER)

Hey @pmanca – please see my last reply. I changed the request to initiate OAuth access based upon your suggestion, but that just gives a different error. Is it possible to connect a non-Marketing Hubspot portal to an application with some Marketing-only scopes, as long as those Marketing-only scopes are optional? If so, how should the OAuth URL be formatted?

Thanks again for your help!


@mattstitch What is your app that you are installing trying to do? Are you trying to perform marketing related activities? Does the install work on a portal that has the marketing tools.

Yes it is possible but you need to make sure the actions the app is taking will not conflict with the scopes.


@pmanca It’s an app with multiple tenants, some of whom may be non-Marketing. The app fetches data from the API endpoints for Contacts, Forms, etc. I believe this part of the HubSpot OAuth documentation is applicable:

If your app can work with multiple types of HubSpot accounts, you can use the optional_scope parameter to include any scopes you work with that only apply to marketing accounts, so that customers using CRM accounts can still authorize your app. Your app will be responsible for checking for and handling any scopes that you didn’t get authorized for.

Is optional_scope appropriate for our use case?


What is this at the end of your call?



@pmanca It’s an OAuth 2.0 base64 state string, which contains some of our app state and a signed nonce.


@mattstitch Just out of curiosity does it work if you remove it from the call? The state is not a supported parameter on our calls.


@pmanca I believe removing the state query param has no effect.


^ that URL still results in

Uh oh!
Insufficient scopes were provided. Please contact the integrator.


@mattstitch Can you print out the full error from the console?


@pmanca No problem. When attempting to authenticate our HubSpot app through a test portal, our application directs a user to:


On that page, I believe this failing XHR is the important one – a POST request to


which returns a 400 with this response body:

  "status": "MISSING_SCOPE_GROUP",
  "message": "client requires more scopes",
  "correlationId": "dbcbe0ab-1bf3-4ed8-be38-1e9dce75f302",
  "requestId": "65a70a56b5e5b21931fd40f340e0aa76"

Here is the POST body:

  "clientId": "<client-id>",
  "hubId": <portal-id>,
  "optionalScopes": [
  "redirectUri": "<callback-url>",
  "responseType": "code",
  "scopes": [

It looks like the query parameters from the initial request are being properly ferried to the /application-authorizations endpoint. It’s not clear what additional scopes are required – the only one I required (contacts) was the only non-Marketing one.


@mattstitch If you check any of the below scopes then they need to be required scopes. Your requests are correct but you might need to change your app settings. Any optional_scopes must be handled in your code and not through the app.

Your code is asking it as an optional scope but your app settings are overriding it as a required scope.


@pmanca Ah, I think I finally understand. Our HubSpot app settings need to define the minimum set of scopes that our app requires. The optional_scope param can be used to request additional scopes. I don’t think I realized that the app settings needed to match the scope param in the OAuth authorization URL.

Concretely, our app settings should only have Contacts checked, and then our users will authorize our app at this URL:


which will give us permission to access the optional scopes as well: Content, Reports, Automation, and Forms. If the user’s HubSpot portal does not support any of those optional scopes, our app will of course not be able to access those resources, but for Marketing HubSpot users, our app will have access.

Am I understanding correctly?


@mattstitch yes that sounds correct to me. Let me know if that works please


@pmanca That appears to have worked – I was able to successfully authorize the app with a non-Marketing HubSpot portal. Thanks for your patience in clarifying that issue for me and my team.


I am having a similar problem with a customer’s account (I don’t have direct access). Our app requests for “content”, “reports”, “social”, “automation”, “forms” as required scopes and “contacts”, “timeline”, “files” as optional scopes. All the scopes are requested via oauth call and not through settings (all the scopes are unchecked in settings)

This worked with the demo account and our own accounts but when a marketing only account try to go through the oauth flow the customer is getting “you do not have the correct role to grant these permissions”.

Where do we go from here to fix the problem?


@Ka-Hing_Cheung That error might be occurring if the person trying to install the app does not have administrator permissions on the portal to do so. That sounds more like a permissions issue then a scope issue.


Where is that permission setup? The user is both “marketing administrator” and “account administrator”. In the other instance the user is just “marketer”


@Ka-Hing_Cheung It is the portal settings under the roles and users.