What is it?

HubSpot’s new granular OAuth scopes are now generally available, replacing the broad files, timeline, tickets, and hubdb OAuth scopes with more precise permissions that reflect the specific resources and actions an app needs.

We’re also launching the Granular Scope Migration Tool in public beta. Available in your HubSpot developer account, this guided experience allows developers of legacy public apps and Projects-based apps using marketplace distribution to review recommended replacement scopes, customize their permissions, and migrate on their preferred timeline.

Why does it matter?

Broad OAuth scopes can grant access to multiple capabilities under a single permission. This makes it harder for developers to limit an app’s access and harder for customers to understand what they are approving.

Granular scopes provide a more exact view of an app’s permissions. They separate access by object and action, including read, write, delete, and publish, and require distinct authorization for higher-risk capabilities. Sensitive actions, including bulk deletion, publishing, and access to high-risk data subsets, require separate scope grants.

This allows developers to request only what their apps require while giving customers greater confidence in the apps they connect to HubSpot. Clearer permissions can also reduce installation friction and support app adoption.

How does it work?

New granular scopes

This change affects apps and service keys that use at least one of the deprecated scopes below. These scopes will sunset on March 1, 2027:

• timeline → timeline.read, timeline.write
• files → files.read, files.write, files.delete
• tickets → crm.objects.tickets.read, crm.objects.tickets.write, crm.schemas.tickets.read, crm.schemas.tickets.write
• hubdb → hubdb.tables.read, hubdb.tables.write, hubdb.tables.publish, hubdb.rows.read, hubdb.rows.write

Apps that already use these scopes will continue to work during the migration window. New apps, and existing apps requesting these permissions for the first time, must use the granular replacements.

HubSpot plans to release additional granular scopes quarterly, with sunset dates occurring twice a year, aligned to date-based versioning.

Migration options by app type

Legacy private apps, Projects-based apps using private distribution, and service keys do not need to take action. HubSpot will migrate them automatically when the broad scopes sunset, preserving their existing effective permissions with no interruption.

Legacy public apps and Projects-based marketplace distribution apps can self-migrate with the Granular Scope Migration Tool. We recommend completing this process before Mar 1, 2027 so you can update and test your app ahead of the automatic migration.

Self-migrating your app

To begin a migration:

1. In your app developer account, go to Development > Migrations.
2. Select Start for the pending scope migration.
3. Review HubSpot’s recommended replacements or customize the scopes your app will request.
4. Apply the migration.
5. For Projects-based apps, sync the updated configuration to your local project.
6. Replace broad scopes in your app’s authorization URLs.
7. Update any scope-introspection logic that checks for broad scope names.

When the migration is applied, HubSpot updates the app configuration and refreshes tokens for existing installations. Customers do not need to reauthorize the app.

Key dates

• - Sep 8, 2026: Granular scopes become available, and the corresponding broad scopes are deprecated.
• - Sep 8, 2026 - Mar 1, 2027: Public and marketplace app developers can migrate using the self-service tool.
• - Mar 1, 2027: The broad scopes stop working, and HubSpot automatically migrates any remaining affected apps and service keys. All app updates after this date must use granular scopes.

Changes to prepare for before sunset

Public and marketplace apps that are automatically migrated may require two additional updates:

• - Authorization URLs: URLs containing a sunset broad scope will no longer work for new installations. Replace those scopes with their granular equivalents before Mar 1, 2027.
• - Scope introspection: Token introspection and token-exchange responses will return granular scope names after migration. Update any logic that checks for the deprecated names.

Apps that complete the self-service migration will not be included in the automatic migration.

Who gets it?

Granular OAuth scopes are available across all HubSpot products and tiers.

The beta Granular Scope Migration Tool is available to legacy public apps and Projects-based apps using marketplace distribution. Private apps, Projects-based apps using private distribution, and service keys will be migrated automatically and will not have access to the tool.