> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Update your app to use granular scopes
> Learn how to migrate an app from legacy broader scopes to the corresponding 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.
| Coarse-grained scope | Granular scopes |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `hubdb` | `hubdb.tables.read`
`hubdb.tables.write`
`hubdb.tables.publish`
`hubdb.rows.read`
`hubdb.rows.write`
|
| `tickets` | `crm.objects.tickets.read`
`crm.objects.tickets.write`
`crm.schemas.tickets.read`
`crm.schemas.tickets.write` |
| `timeline` | `timeline.read`
`timeline.write` |
| `files` | `files.read`
`files.write`
`files.delete` |
## 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.
Existing installs of your app keep working with their current access while a migration is available. You choose when to apply the update, up until the migration's automatic rollout date.
## 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`](/docs/developer-tooling/local-development/hubspot-cli/project-commands#download-from-hubspot) 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.
While a migration is in progress, you can't add new scopes to the app, and deploys require a matching local configuration. Once the migration finishes, you can resume updating scopes for your app.
## 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.
**Please note:** only turn off backward compatibility after both your install URLs and your scope-checking code use granular scopes directly. Turning it off too early can break live integrations.