HubSpot OAuth v1 Is Going Away: A Practical Plan for Older CRM Integrations

By Greg Nowak. Last updated 2026-07-24.

HubSpot’s legacy OAuth v1 endpoints will remain available until February 16, 2027. After that date, v1 calls will begin returning errors. For an older CRM integration, that can mean failed token refreshes, disconnected workflows, broken reporting, or an app that appears healthy until its next authentication request.

This is particularly relevant to businesses with custom middleware, agency-built apps, internal reporting tools, lead-routing services, or integrations inherited from a previous supplier. The visible CRM workflow may be stable while the authentication code underneath it is years old.

The good news is that HubSpot has kept the migration reasonably contained. The installation URL, consent screen, and requested scopes do not change. The main work is in the backend: finding every legacy OAuth call, replacing it, checking the new response model, and proving the full token lifecycle still works.

First, establish whether you are affected

Do not start by assuming that “the HubSpot integration” is one application. Authentication logic often appears in the main service, background workers, serverless functions, support utilities, test fixtures, and scripts used only when a customer disconnects.

Search repositories and deployment configuration for the legacy paths:

rg -n '/oauth/v1/(token|access-tokens|refresh-tokens)' .

Also inspect API gateway logs, APM traces, environment-specific configuration, CI/CD variables, third-party automation tools, and any shared OAuth wrapper used across client projects. If HubSpot sent a marketplace-app notification containing affected app IDs, use that list as the starting point—but not as proof that you have found every call.

Finding	Priority	Recommended response
Production code calls OAuth v1	Immediate	Inventory the affected customers and schedule migration and regression testing.
A background refresh worker uses v1	Immediate	Update it early; failure could affect every connected account as tokens expire.
Only tests or old scripts reference v1	Medium	Confirm they are genuinely unused, then update or retire them so they cannot be restored later.
The integration uses OAuth v3	Planned	Move to the date-based 2026-03 paths and confirm sensitive fields are sent only in request bodies.
No source code or technical owner can be found	High	Treat ownership and recoverability as project risks, not merely documentation gaps.

A practical triage matrix for deciding where the OAuth migration work should begin.

What changes in the new API

The legacy token endpoint, token-information lookups, and revoke call are replaced by three date-based endpoints:

POST /oauth/2026-03/token handles the authorization-code exchange and token refresh.
POST /oauth/2026-03/token/introspect replaces the old access-token and refresh-token metadata requests.
POST /oauth/2026-03/token/revoke replaces deletion of a refresh token during disconnect or uninstall.

Sensitive parameters must be supplied as application/x-www-form-urlencoded request-body fields, rather than being placed in the request URL or path. This reduces the chance of client secrets and tokens being retained by proxies, logs, browser history, or monitoring systems.

Refresh logic should read the returned expires_in value instead of relying on a hard-coded assumption. HubSpot currently documents 30-minute access tokens, but code should still honour the response. Avoid imposing a fixed storage-length limit on tokens, because HubSpot does not define a maximum token size.

Introspection is more than an endpoint rename. Its response includes fields such as active and token_use, so any code that consumes the old metadata model must be updated. Error handling should use the standard error and error_description fields. HubSpot’s older status and message fields remain available for compatibility, but they should not be the foundation of new conditional logic.

Treat this as a small migration project, not a search-and-replace

A dependable delivery plan has five parts:

Inventory: record each affected app, repository, environment, customer group, endpoint, and technical owner.
Update: replace token exchange, refresh, introspection, and revocation calls. Keep secrets out of URLs and redact OAuth callback query strings from logs.
Test: exercise a new installation, an existing refresh token, access- and refresh-token introspection, disconnect or uninstall, invalid credentials, revoked tokens, and expired authorization codes.
Release: deploy in stages where possible. Monitor OAuth-related 4xx responses, refresh failures, reauthorization requests, and disconnect errors.
Close: rerun the legacy-path search, review production telemetry, remove temporary compatibility code, and capture evidence that no v1 traffic remains.

Testing only a fresh installation is not enough. Older customer accounts may have different token records, scopes, or operational paths. Include at least one representative long-running connection in the rollout plan, without exposing its credentials in test output.

Keep platform-version work separate

Some teams will discover a second issue while auditing the app: an old HubSpot developer-platform version. That work may share developers and test environments with the OAuth migration, but it is not the same change.

For a project already on platform version 2025.2, HubSpot documents changing platformVersion in hsproject.json to 2026.03, then running hs project upload. Older project versions use hs project migrate; legacy public apps outside the projects framework use hs app migrate. HubSpot recommends CLI version 8.4.0 or later. Environment variables from an older serverless.json may need to be recreated with hs secret add.

Scope these tasks together only when doing so simplifies testing and ownership. Combining unrelated upgrades into one large release can make rollback and fault-finding harder.

What management should ask for

A business owner does not need a tour of OAuth internals. Ask for a short inventory, named owners, affected customers or workflows, a tested rollback approach, production monitoring, and a completion date comfortably ahead of February 16, 2027.

If the integration has unclear ownership or several agency handovers behind it, a focused technical audit is often the fastest way to turn the deadline into a bounded project. Talk to Greg about reviewing the integration and shaping a practical migration plan.

Related on GrN.dk

Need help with this kind of work?

Plan your HubSpot integration migration Get in touch with Greg.

Sources

Last modified

2026-07-28