Contacts scope migration for app partners

What is it?

HubSpot is splitting the contacts scope into more granular CRM scopes that will allow you to choose separate access for contacts, companies, and deals (e.g. contacts.read, companies.write, etc.) This will enable you to request only the scopes that are absolutely necessary for your app.

With privacy and security being a top priority for HubSpot, all app partners using the contacts scope will be required to migrate to granular CRM scopes by February 28, 2022. Migrating to granular CRM scopes will be a requirement to remain in HubSpot's App Marketplace by 2022.

Requesting only the information and permissions that are necessary for an app helps build customer trust, while keeping HubSpot's commitment to data privacy and security. Previously, because developers lacked a way to separate out CRM scopes, apps were over-requesting customer data as a requirement for installation. This forced users to choose between installing an app without control over the data shared with third parties or not installing the app at all. With granular scopes, you'll be able to request access to only the specific data you need.

How does the migration work?

Beginning on November 1, 2021, app partners will have their apps automatically be migrated to use granular CRM scopes. There'll be no customer impact since HubSpot will be reducing your app's access to their data and they won't need to reauthorize your app. There will be no impact to your app since HubSpot designed a trial migration to ensure your app will not break.

Once the auto-migration is complete you will receive an email confirmation from HubSpot, at which time you'll be required to update your install URL for new app installs and any code that references the old contacts scope by February 28, 2022. The legacy contacts scope will be officially deprecated on July 31st, 2022, so you will need to make these updates for your app to continue working.

For app partners that you opt out of the auto-migration process, you must complete the manual migration by February 28th, 2022 using the migration wizard. If you haven't migrated your app by February 28, 2022, it will automatically be migrated.

To make the migration process as easy as possible, HubSpot will be automatically migrating your app to granular CRM scopes beginning on November 1, 2021:

1. Your app is migrated to granular CRM scopes beginning on November 1, 2021 (no action is required from you in this step).
2. You'll receive an email notification to update your app's install URL for new app installs, along with any code that references the deprecated contacts scope once the migration is complete.
3. Update your install URL for new app installs and any associated code referencing the old contacts scope by February 28, 2022. You will need to make these updates for your app to continue working.
   1. Log in to your developer account.
   2. If your app is using the CRM v3 APIs, scroll down and click Scopes to expand the section. Unselect any scopes your app doesn't need, then click Save.
   3. Scroll down to the Install URL (OAuth) section. Click Copy full URL.
   4. Update your install URL wherever users install your app. You can update the URL on the HubSpot app listing page by selecting Install app and updating your OAuth URL on the linked page.
   5. Replace any references in your app's code to any the contacts scope and replace them with the associated granular CRM scopes (e.g., replace contacts with crm.objects.contacts.read).

For apps that you opted out of the auto-migration process, you must complete the manual migration by February 28th, 2022 using the migration wizard. This wizard will recommend granular CRM scopes based on your app's historical API usage and update scopes for both existing and new installs of your app. Learn more about the manual migration process by watching this video demo.

The migration should take about 60 minutes depending on what kind of testing you’d like to do. HubSpot recommends migrating a test app before migrating your production app. The migration should not impact new or existing installs. If you run into any issues, you can roll back the changes in step 6 below. You will need to refresh your app’s tokens in step 6b, so keep that in mind if you need to set that up before beginning the migration.

1. Log into your HubSpot developer account.
2. Click Manage apps.
   
3. Find your app and click Ready for scope migration.
   
4. Read through the details on the migration process, then click Next.
   
5. Review and update the new granular scopes that your app will use:
   1. Click Review recent API calls to see your recent API calls to see which scopes they've been using.
   2. If needed, adjust your scopes in the bottom section by selecting the checkbox next to the corresponding scope.
   3. Click Next.
      
6. Next, update the scopes for existing installs of your app:
   1. Click Begin update to update the scopes to granular scopes on HubSpot’s side.
      
      
      
   2. In your app, refresh your access tokens to update the scopes on your app’s side. Once your tokens are refreshed, click Confirm: All tokens refreshed.
      
   3. At this point, you can do whatever testing you’d like to do to verify the new scopes are working as intended. See Testing for some suggested tests. If you encounter any issues, check out the Rollback section below.
   4. Once you’ve verified everything is working correctly, select the Verify new scopes work as intended checkbox, then click Next.
      
7. Update your app's install URLs and deprecated scope references:
   1. Update any OAuth install URLs to request granular scopes. Your specific URL will depend on your app, but you can refer to the suggested new install URL to get an idea of what this should look like. Select the Update any OAuth install URLs checkbox once complete.
   2. Update your app’s code anywhere else scopes are referenced, then select the Update your app's code anywhere else the scopes are referenced checkbox.
   3. Click Done to finish the migration process.
      
8. After you've completed the migration, the Ready for scope migration label should no longer appear next to your app.
   

Every app is different so the steps below outline some suggested testing that you could do. HubSpot recommends testing existing and new installs to make sure new scopes are working correctly. If you’re at step 6b above in the migration wizard:

1. Open a new tab and go to your HubSpot developer account.
2. Click Manage apps.
3. Click on your app name.
4. In the left sidebar menu, click Monitoring. If any errors occurred, you can review them on the API calls tab.
   
5. Test existing installs of your app:
   1. In your app, trigger an API call, such as creating a new contact.
   2. In HubSpot, watch for errors on the Monitoring page.
   3. If you see a 403 error, this probably means you need to request additional scopes. See Rollback.
6. Test new installs of your app.
   1. In your app, create a new connection to HubSpot.
   2. In HubSpot, watch for errors on the Monitoring page.
   3. If you see a 403 error, this probably means you need to request additional scopes. See Rollback.
7. If all of your testing was successful, return to the migration wizard, and continue following the manual migration instructions above, resuming from step 6c.

If you encounter an issue during the migration or while testing, you can roll back to your original scopes (see video demo):

1. In the migration wizard, click Roll back updates.
   
2. In the dialog box, click Roll back scopes. This will revert your app to original scopes on HubSpot’s side.
   
3. You'll then be prompted to refresh your access tokens. This will revert your app to original scopes on your app’s side. After you've refreshed your access tokens, click Confirm: All tokens refreshed.
   
4. You'll be returned to the Review new granular scopes step of the migration wizard with a message recommending that you review your new scopes to prevent errors with your app. If you saw 403 errors during testing, it’s most likely because you needed to select additional scopes. Select those scopes in the bottom section.
   
5. Continue with the migration wizard. If you still encounter 403 errors, repeat steps 1-4 of the rollback process above.

If you see the pop-up below titled There was a problem migrating your app’s scopes, that means there was an unexpected error on HubSpot’s end. HubSpot will be notified and look into the issue. In the meantime, please refresh your scopes to revert your app to its original scopes. HubSpot will email you when the issue is resolved and you can attempt the migration again.