How to set up your scopes in HubSpot

October 30, 2024

This guide explains how to correctly configure the advanced scopes settings in your HubSpot developer app for seamless integration with Unified.to. We'll cover setting up both required and optional scopes, and address some common issues you might encounter.

Before you begin

This guide assumes you have a basic understanding of:

Scopes

Set up required scopes in HubSpot

Note: If you are using webhooks, please refer to: How to configure webhooks in HubSpot

Log in to your HubSpot developer account and navigate to your app settings.
Look for the Advanced scopes setting toggle. If it's turned Off, switch it On.
If you are not using webhooks, then Unified.to only requires two scopes to be set as Required: crm.objects.owners.read and oauth
1. Click + Add new scope
2. Select crm.objects.owners.read
3. Set it as a Required scope
Save your changes.

If you're only using the Unified.to pre-built HubSpot integration for sign-in, you're all set!

Otherwise, if you are not using webhooks but still plan to read or write data, you'll need to set up additional optional scopes. Continue to the next section.

Set up optional scopes in HubSpot

Determine which Unified.to features you'll be using. For example, if you want to read companies from HubSpot, you'll need the crm.objects.companies.read scope.
Click + Add new scope again.
Select the appropriate scope(s) for your needs.
Set these additional scopes as Optional.
Save your changes.

You can find the full list of scopes that are used by Unified.to here.

Configure your scopes on Unified.to

Be sure to also configure these scopes in your Unified.to settings. For instructions on how to do that, refer to our Scopes guide.

Understanding HubSpot's scope constraints

HubSpot has some specific rules about how scopes work:

If you specify a scope as Required, it must be included in every authorization request.
- Note: If you intend to read data via a webhook, then the read scope for that object must be marked as Required in HubSpot.
Optional scopes may or may not be included in the authorization.
If you don't specify a scope at all, it cannot be included in the authorization request.
The OAuth scope cannot be removed and must always be required.

Behind the scenes, Unified.to will request scopes according to what you have configured on the platform:

We'll always request crm.objects.owners.read as a Required scope
When you enable webhook scopes on Unified.to, we convert every read scope to required, assuming they'll all be used for webhooks.
Otherwise, if you have not enabled the webhook scope, then all other scopes will be requested as Optional.

In general, we recommend that you only stick to requesting scopes for the data you actually need. For more instructions on setting up scopes to work with webhooks, please refer to: How to configure webhooks in HubSpot

What your users will see

When your users sign in with HubSpot, they'll see a screen requesting access to the scopes you've specified:

Required scopes will always be shown and cannot be deselected.
Optional scopes will be shown and can be deselected by the user.

Troubleshooting

If your HubSpot scopes don't match the requested scopes via Unified.to, your users may see an error message about there being a scopes mismatch.

Double-check that:

All scopes in your HubSpot app are included in every Unified.to request.
All scopes requested by Unified.to are specified (either as required or optional) in your HubSpot app.
If you're using webhooks, ensure all read scopes are set as Required in your HubSpot app.
If you're not using webhooks, ensure all scopes aside from oauth and crm.objects.owners.read are set as Optional.