Update your app to use granular scopes

Starting on September 8, 2026, HubSpot has introduced new granular scopes to replace the remaining coarse-grained scopes for specific APIs. Historically, these coarse-grained legacy scopes granted broad access, including both read and write access for an object in a singular scope. Now, these scopes are all split into narrower ones (e.g., separate read and write access or per-object access). HubSpot provides an in-app tool to help you smoothly migrate any of your existing apps to the newer scopes from directly within your account. This guide provides context on the affected scopes, and walks you through the migration process.

​

Coarse-grained scopes

The table below outlines the coarse-grained scopes that should be migrated to the newer, granular equivalents.

​

Migration timeline

Each affected app will include an Auto rollout date you’ll be able to review in your HubSpot account. If you don’t apply a migration by that date, HubSpot applies the update for you automatically so your app keeps working. To stay in control of exactly which scopes your app requests, it’s recommended that you apply migrations yourself before the Auto rollout date, especially if you want to customize the scopes rather than take the recommended set.

​

Before you migrate

Keep the following in mind as you assess any apps that need to be migrated:

• Each app can have multiple scope migrations available at a given time. You can review each proposed migration before proceeding.
• Finishing a migration differs based on app type:
  • UI-based and legacy apps: these apps are managed in HubSpot with no project-based configuration. Once you apply the update, no further action is required.
  • Project-based apps: these apps are managed with a local project and a app-hsmeta.json configuration file. After you apply an update, you’ll need to sync your local configuration and re-deploy. The in-app migration tool will guide you through the process, but it’s recommended you download the project locally using the hs project download command.

If your affected app is project-based, you’ll be prompted with a warning when you run hs project upload. Any apps that have completed the migration process will also appear.

​

Migrate your app scopes

To review affected apps eligible for migration and begin the migration process:

• In your HubSpot account, navigate to Development.
• In the left sidebar menu, click Migrations.
• Review the list of affected apps and their associated migration statuses.

​

Review available migrations

Each of your affected apps will be listed for you to review, along with the corresponding legacy scopes, and their migration statuses, along with an Auto rollout date when the recommended update will automatically be applied if no action is taken.

​

Customize and initiate migration for an app

To review the migration steps for an app:

• Click Start next to a specific scope, or click Start all [X] to migrate all coarse-grained scopes to their granular equivalents.
• On the Intro page, read about what will change, and what will happen when you initiate the migration. Note that you’ll have a chance to confirm all changes, and new access won’t change for existing installs. Click Next.
• Next, review and optionally customize which scopes your app will request after migration.

• On the left, under Review the update, choose an option:
  • Use recommended: HubSpot selects the new scopes that will preserve your app’s current access. Existing installs will continue working with no loss of access. Choose this option if you want the safest, fastest path.
  • Customized (advanced): choose exactly which new scopes your app requests, select the checkboxes next to each one as required, conditionally required, or optional. Choose this if you want to reduce your app’s access or fine-tune what it requests. You can change individual scope types after the migration.

• By default, the Backward compatibility switch is set to on.
  • While it’s on, HubSpot expands legacy scopes to the new granular scopes on authorization (install) URLs, and returns the legacy scope name from token responses, so existing integrations keep working during the transition.
  • It’s highly recommended that you leave this setting on, unless your app builds its own OAuth install URL, or has code that reads scope names from the token exchange or token responses.
  • When you’re ready to stop relying on backward compatibility, you can later turn this setting off.
• Click Next.
• On the Update & finish page, you’ll apply the associated changes:
  • On the left, under 1. Apply in HubSpot, click Apply update. You’ll be prompted to fully confirm the change, then your app’s configured scope(s) will be updated accordingly.
  • Once you apply the update, the status will change to Completed for UI-based and legacy apps, or Applied — awaiting sync for project-based apps.
  • Optionally, if you build the OAuth install URL yourself, you can copy the updated install URL. If you toggled the Backward compatibility switch off in the previous step, you can customize the updated optional, conditionally required, and required scopes before copying the corresponding install URL.

• For project-based apps, your local project configuration will need to be synced so it matches the scope changes and you can resume deploying:
  • While still on the Update & finish page, click Copy file under the 2. Replace your local app-hsmeta.json step.
  • Replace the contents of your local app-hsmeta.json file with the copied configuration. If you opted for a Customized migration in the previous Review step of the migration process, make sure to test your app against the new scopes before you deploy.
  • Deploy your project by running hs project deploy.
  • HubSpot will verify that your local configuration matches the new scopes. Once the verification succeeds, the status will switch to Upload verified.

• Click Finish to complete the migration.

​

Turning off backward compatibility after migrating

If your app builds its own OAuth install URL, or has code that reads scope names from the token exchange or refresh, and you no longer need to rely on backward compatibility, you can optionally turn the setting off:

• Update your app’s install URLs to request the granular scopes directly.
• Update any code that reads scope names so it checks for the granular scopes instead of the legacy scope.
• In your HubSpot account, navigate to Development.
• In the left sidebar menu, click Migrations, then locate your app and its completed migrations.
• Find the completed migration, then click to toggle the Keep legacy scopes working switch off for the migration. You can change this setting from the completed migration at any time.