--- title: "How to set up your scopes in HubSpot" img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_your_scopes_in_hubspot-icon.png date: 2024-06-11T00:00:00.000Z tag: Guides description: "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..." url: "https://docs.unified.to/guides/how_to_set_up_your_scopes_in_hubspot" --- # How to set up your scopes in HubSpot ------ _June 11, 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](https://docs.unified.to/concepts/scopes) - [How to create a connection (Project) ](https://docs.unified.to/guides/how_to_create_connection_with_hubspot) - [How to get your HubSpot developer key and OAuth 2 credentials (Legacy App)](https://docs.unified.to/guides/how_to_get_your_hubspot_developer_key_and_oauth_2_credentials_legacy_apps) ## Set up required scopes in HubSpot (Project) 1. Go to [https://offers.hubspot.com/free-cms-developer-sandbox](https://offers.hubspot.com/free-cms-developer-sandbox), Sign in. 2. Development → Project → select your project 3. In your project(code) you will see following folder structure. GOTO→ yourproject (account-testing) → app-hsmeta.json ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_your_scopes_in_hubspot-0.png) 1. Following will be the scopes and redirect URL. You can remove which you want. However, do remember those removed scopes before creating a connection in unified. Also remember to add redirect URL as follows. ```javascript { "uid": "get_started_app", "type": "app", "config": { "description": "A Unified.to token app for testing", "name": "My Get Started app", "distribution": "private", "auth": { "type": "oauth", "redirectUrls": [ "https://api.unified.to/oauth/code", ], "requiredScopes": [ "oauth", "crm.objects.companies.read", "crm.objects.contacts.read", "crm.objects.deals.read", "crm.objects.owners.read", "crm.pipelines.orders.read", "crm.objects.contacts.write", "crm.pipelines.orders.read", "crm.pipelines.orders.write", "crm.objects.deals.write", "sales-email-read", "content", "tickets", "crm.lists.read", "settings.users.teams.read" ], "optionalScopes": [], "conditionallyRequiredScopes": [] }, "permittedUrls": { "fetch": ["https://api.hubapi.com"], "iframe": [], "img": [] }, "support": { "supportEmail": "support@example.com", "documentationUrl": "https://example.com/docs", "supportUrl": "https://example.com/support", "supportPhone": "+18005555555" } } } ``` 1. You can update those changes using following command in terminal. ```javascript hs project upload ``` 1. When the code is uploaded successfully you can check that by going to following Development→ Project → Select your project. ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_your_scopes_in_hubspot-1.png) 1. To check your scopes click on the project Component. It will show your app-hsmeta.json ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_your_scopes_in_hubspot-2.png) ## Set up required scopes in HubSpot (Legacy App) **Note**: If you are using webhooks, please refer to: [How to configure webhooks in HubSpot](https://docs.unified.to/guides/how_to_configure_webhooks_in_hubspot) 1. Go to [https://offers.hubspot.com/free-cms-developer-sandbox](https://offers.hubspot.com/free-cms-developer-sandbox), Sign in. 2. Development → Legacy App→ Your New App 3. In the same Auth tab, scroll 4. If you are not using webhooks, then [Unified.to](https://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 ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_your_scopes_in_hubspot-3.png) ## 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](https://app.unified.to/integrations/hubspot?tab=oauth2) ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_your_scopes_in_hubspot-4.png) 1. Make sure to select optional ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_your_scopes_in_hubspot-5.png) 1. Add all the scopes you need 2. Save your changes ### Configure your scopes on [Unified.to](https://unified.to/) Be sure to also configure these scopes in your [Unified.to](https://unified.to/) settings. For instructions on how to do that, refer to our [Scopes guide](https://docs.unified.to/concepts/scopes). ## 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](https://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](https://unified.to/), we convert every Hubspot scope ending with `.read` 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](https://docs.unified.to/guides/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. ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_your_scopes_in_hubspot-6.png) ## Specifying Required vs Optional Scopes Unified tries to automatically classify scopes as required or optional. If you need additional control, you can always specify this information in the `scopes` URL parameter. Just prefix the Hubspot-specific scope with `required:` or `optional:` and we will handle them correctly. eg. `required:crm.objects.contacts.read` ## Troubleshooting If your HubSpot scopes don't match the requested scopes via [Unified.to](https://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](https://unified.to/) request. 2. All scopes requested by [Unified.to](https://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`](https://crm.objects.owners.read/) are set as **Optional**. ## See also - [Understanding scopes](https://docs.unified.to/concepts/scopes) - [How to configure webhooks in HubSpot](https://docs.unified.to/guides/how_to_configure_webhooks_in_hubspot) - [How to troubleshoot unhealthy connections](https://docs.unified.to/guides/how_to_troubleshoot_unhealthy_connections#how-to-troubleshoot-unhealthy-connections)