Skip to content
HubSpot Developer Changelog

Upcoming: contacts scope sunset

Last year HubSpot split the contacts scope into more granular CRM scopes, to provide app developers separate access for contacts, companies, and deals (i.e.,, companies.write, etc.). With privacy and security being a top priority for HubSpot, we will be removing the contacts scope on Jul 31, 2022.

What does this mean for you?

All public app developers currently using the contacts scope will need to complete the migration process by July 31, 2022.

If you're working with Private Apps, you should not need to make any changes, as Private Apps have only supported granular scopes since they launched.

Migration process

All apps using the contacts scope have had  the OAuth settings updated to use the granular CRM scopes. To complete your app migration and prevent your app from breaking upon contacts scope deprecation:

  1. Log in to your developer account, and go into the auth settings for your app.
  2. Scroll down and click Scopes to expand the section. If you see any scopes selected that your app no longer uses, remove them and then save the settings.
  3. Scroll down to the Install URL (OAuth) section. Click Copy full URL.
  4. Update your install URL wherever users install your app. This would be the link that HubSpot users use to connect your app to their account. If your app is in the HubSpot App Marketplace, this link would be presented to users on the page that they get to when they click Install app.
  5. Replace any references in your app's code to the contacts scope and replace them with the associated granular CRM scopes (e.g., replace contacts with


When is this happening?

The contacts scope will no longer function starting on July 31st. After this, any OAuth authorizations using the contacts scope will result in an error. This will include users installing apps in a HubSpot account, as well as refreshing access tokens.

Please let us know if you have any questions by joining the discussion in our community.