Unified.to
All articles

How to set up your scopes in HubSpot

July 3, 2025

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:

Set up required scopes in HubSpot

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

  1. Go to https://app.hubspot.com/developer, select your app
  2. In the same Auth tab, scroll down and go to the scopes section
  3. 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
    4. Save your changes

Setup optional scopes

  1. You can see the list of scopes required for the objects you need at https://app.unified.to/integrations/hubspot?tab=oauth2

  1. Make sure to select optional

  1. Add all the scopes you need
  2. Save your changes

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:

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

See also

All articles