What This Update Actually Is
HubSpot deprecated four broad OAuth scopes and replaced them with specific, action-level equivalents. This change is now generally available across all HubSpot products and tiers.
Here's exactly what replaced what:
- timeline splits into: timeline.read, timeline.write
- files splits into: files.read, files.write, files.delete
- tickets splits into: crm.objects.tickets.read, crm.objects.tickets.write, crm.schemas.tickets.read, crm.schemas.tickets.write
- hubdb splits into: hubdb.tables.read, hubdb.tables.write, hubdb.tables.publish, hubdb.rows.read, hubdb.rows.write
HubSpot also shipped the Granular Scope Migration Tool. It came out in public beta on September 8, 2026, and went generally available on October 15, 2026. It lives inside your developer account under Development > Migrations.
New apps must use granular scopes from day one. Existing apps using these scopes for the first time must also use the granular versions. Apps already using the old scopes continue working until March 1, 2027.
Why HubSpot Shipped This
Broad OAuth scopes created two real problems. First, they gave apps more access than they actually needed. Second, they made it nearly impossible for the humans approving those permissions to know what they were really agreeing to.
When a single scope like "tickets" covers read, write, schema changes, and more, a developer can't scope down to just what their app needs. And a customer installing that app has no idea what they're opening up.
Granular scopes fix both problems at once. Developers request only what they need. Customers see exactly what they're approving. HubSpot notes that clearer permissions also reduce installation friction, which means better conversion for apps in the marketplace.
Sensitive actions now require separate grants. Bulk deletion, publishing, and access to high-risk data subsets won't be bundled into a single broad permission anymore. That's a meaningful trust upgrade for everyone in the ecosystem.
How to Use It Step by Step
If you maintain a legacy public app or a Projects-based marketplace distribution app, here's the migration path:
- Open your HubSpot developer account and go to Development > Migrations.
- Select Start next to the pending scope migration.
- Review HubSpot's recommended replacement scopes. Customize if your app needs fewer permissions than the default recommendations.
- Apply the migration. HubSpot updates your app config and refreshes tokens for all existing installations automatically. Customers don't need to reauthorize.
- For Projects-based apps, sync the updated configuration to your local project.
- Replace any broad scope names in your app's authorization URLs with their granular equivalents.
- Update any scope-introspection logic that checks for the old broad scope names. After migration, token introspection responses return granular names only.
Private apps, Projects-based apps using private distribution, and service keys don't need to touch anything. HubSpot will migrate them automatically on March 1, 2027, with no interruption to effective permissions.
What It Touches in Your HubSpot Strategy
This update lives at the developer and integration layer, but it ripples into a few areas that ops and technical leaders should track.
Any third-party or custom app connecting to HubSpot via OAuth is in scope. That includes integrations built on HubDB for dynamic web content, ticket-based service workflows, file management tools, and timeline event logging. If your team built or licensed an app that touches any of those objects, someone needs to confirm its migration status before March 1, 2027.
Key Takeaway
Authorization URLs containing deprecated broad scopes will stop working for new installations after March 1, 2027. If your team uses install links, those URLs need to be updated before sunset regardless of whether the app was auto-migrated.
The HubDB changes are worth a close look for content and ops teams. HubDB powers dynamic website content in some portals. A scope gap or misconfigured migration there could quietly break a content display without triggering an obvious error.
The ticket scope changes also connect to service operations. If your support workflows depend on a custom or third-party app writing to tickets, double-check that app's migration plan. You'll want read and write coverage confirmed before sunset.
This update is part of a broader pattern. HubSpot is tightening API governance across the board. If you're already working with programmatic configuration, you'll recognize the same philosophy behind the Payments Checkout Settings API, which also moved toward explicit, scoped control rather than broad access.
Key Takeaway
HubSpot plans to release additional granular scopes quarterly, with sunset dates twice a year aligned to date-based versioning. This isn't a one-time cleanup. Build a recurring review into your integration maintenance calendar.
For teams managing complex integrations, this kind of deprecation cycle pairs well with a broader integration audit. If you're also navigating HubSpot's Salesforce sync rebuild ahead of the mid-2027 deprecation, now is a good time to inventory every app touching your portal, confirm its scope configuration, and document your migration plan.
Who Should Care Most
This update is primarily a developer and technical ops concern. But a few business-side roles need to be aware of the timeline.
- HubSpot app developers building public or marketplace apps: migrate now using the self-service tool. Don't wait for the automatic migration, because your authorization URLs won't update themselves.
- RevOps and technical admins managing third-party integrations: confirm which connected apps use the four deprecated scopes and check each vendor's migration timeline.
- Agency and partner teams who built custom apps for clients: flag this to clients now. If you built the app, you own the migration. If a vendor built it, get written confirmation of their plan.
- Content and service ops leaders whose portals use HubDB-powered pages or ticket-writing integrations: ask your developer or vendor contact what migration steps they've completed.
Companies with all-private apps and no marketplace distribution can relax. HubSpot handles those automatically. The humans who need to act are specifically those with public or marketplace-distributed apps.
George's Take
I've seen portals where a handful of connected apps held sweeping permissions that nobody on the team could explain anymore. Nobody knew who approved them or why. Granular OAuth scopes don't just make apps more secure; they force a moment of clarity that most integration stacks are long overdue for. If this update prompts your team to finally inventory every app connected to your portal and ask "does this still need to exist and does it need this much access," then it's already paid for itself. The March 2027 deadline is actually a gift. Use the time.
“Granular OAuth scopes don't just make apps more secure. They force a moment of clarity that most integration stacks are long overdue for.”
If your team builds on HubSpot's API or manages a stack of connected apps and you want a clear picture of what needs to change and when, let's talk. Book a strategy call with Sidekick Strategies and we'll walk through your integration inventory, flag the scope changes that affect your portal, and build a migration plan with real deadlines, not guesswork.
Frequently Asked Questions
What are HubSpot's new granular OAuth scopes?
HubSpot replaced four broad OAuth scopes (files, timeline, tickets, hubdb) with specific, action-level permissions that separate read, write, delete, and publish access. This lets developers request only what their app needs and gives customers a clearer picture of what they're approving when they install an app.
When do HubSpot's deprecated broad OAuth scopes stop working?
The deprecated scopes (files, timeline, tickets, hubdb) sunset on March 1, 2027. Apps already using those scopes continue working until that date. After March 1, 2027, HubSpot automatically migrates any remaining affected apps and service keys. All new app updates after that date must use granular scopes.
Do I need to migrate my private HubSpot app to granular OAuth scopes?
No. Legacy private apps, Projects-based apps using private distribution, and service keys are migrated automatically by HubSpot when the broad scopes sunset on March 1, 2027. Their effective permissions are preserved with no interruption. Only public and marketplace distribution apps need to self-migrate using the Granular Scope Migration Tool.
How do I use HubSpot's Granular Scope Migration Tool?
In your HubSpot developer account, go to Development > Migrations, then select Start next to your pending scope migration. Review the recommended replacement scopes, customize if needed, and apply. HubSpot refreshes tokens for all existing installations automatically. Customers don't need to reauthorize. Then update your authorization URLs and any scope-introspection logic.
Will my app's existing customers need to reauthorize after the scope migration?
No. When you apply the migration using HubSpot's self-service tool, HubSpot updates your app configuration and refreshes tokens for all existing installations automatically. Customers don't need to take any action. However, your authorization URLs must be updated before March 1, 2027, or new installs will fail.
What happens if I don't migrate my HubSpot app before March 1, 2027?
HubSpot will automatically migrate your app and update its configuration. However, any authorization URLs still containing deprecated broad scope names will stop working for new installations. You'll also need to update scope-introspection logic manually, since token responses will return granular scope names after the automatic migration runs.




