Contacts Scope Migration

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 apps using the contacts scope will be required to migrate to granular CRM scopes by January 31, 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?

Between November 1-8, 2021, apps will 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 on November 8, 2021, you'll be required to update your install URL for new app installs and any code that references the old contacts scope by January 31, 2022. The contacts scope will be officially deprecated on January 31, 2022, so you will need to make these updates for your app to continue working.

If you would like to opt out of the auto-migration process and manually migrate your scopes, you may do so by completing the opt-out form by October 22, 2021, and completing the migration by January 31, 2022 using the migration wizard. If you haven't migrated your app by January 31, 2022, it will automatically be migrated.

Auto-migration

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

  1. Your app is migrated to granular CRM scopes between November 1-8, 2021 (no action is required from you in this step).
  2. You'll receive an email notification on November 8th, 2021 to update your app's install URL for new app installs, along with any code that references the deprecated contacts scope.
  3. Update your install URL for new app installs and any associated code referencing the old contacts scope by January 31, 2022. You will need to make these updates for your app to continue working.
auto-migration-scope-change-summary-screen

Manual migration

If you want to opt out of auto-migration and prefer to manually migrate your scopes, you may do so by completing the opt-out form by October 22, 2021, and completing the migration by January 31, 2022 using the migration wizard in your HubSpot developer account. The migration 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.
    hs_developer_dashboard
  3. Find your app and click Ready for scope migration.
    sample_app_ready_for_migration
  4. Read through the details on the migration process, then click Next.
    scope_mirgration_wizard_start
  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.
      scope_migration_review
  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.
      scope-migration-begin-update

    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.
      scope-migration-confirm-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.
      scope-migration-verify-scopes-work
  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.
      scope_migration_update_install_url
  8. After you've completed the migration, the Ready for scope migration label should no longer appear next to your app.
    scope_migration_app_complete

Testing

Every app is different so the steps below outline some suggested testing that you could do. We recommend 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.
    scope-testing-monitoring-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.

Rollback

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.
    scope-migration-rollback
  2. In the dialog box, click Roll back scopes. This will revert your app to original scopes on HubSpot’s side.
    scope-migration-rollback-confirm
  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.
    scope-migration-rollback-finished
  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.
    scope-migration-rollback-review
  5. Continue with the migration wizard. If you still encounter 403 errors, repeat steps 1-4 of the rollback process above.

Unexpected Errors

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.
scope-migration-errors