HubSpot has stopped leaving this vague. On March 30, 2026, its REST APIs moved to date-based versioning. Then, on May 12, 2026, HubSpot announced that the OAuth v1 API is deprecated and that the old endpoints will stay live only until February 16, 2027. If a business depends on custom CRM integrations, lead-routing middleware, internal reporting tools, or agency-built automations, older HubSpot auth code is no longer harmless legacy plumbing. It now has a defined deadline and a stated security reason to be replaced.
That security point matters. HubSpot says the v1 endpoints accept sensitive information and tokens in query parameters or the URL path, which can leak secrets into logs, browser history, and telemetry. So an integration can appear stable while still carrying a known exposure pattern in the background. Once the platform vendor has documented that risk in its own changelog, this stops looking like optional tidying and starts looking like sensible paid remediation.
The affected endpoints are familiar to anyone who has worked on older HubSpot integrations: POST /v1/token, GET /v1/access-tokens/{token}, GET /v1/refresh-tokens/{token}, and DELETE /v1/refresh-tokens/{token}. HubSpot's replacements are POST /oauth/2026-03/token, POST /oauth/2026-03/token/introspect, and POST /oauth/2026-03/token/revoke. The job is still OAuth, but the request patterns and security posture are different enough that this deserves a proper fix, not a rushed search-and-replace.
Why this is more than an endpoint rename
HubSpot's migration guide is revealing because it shows where these dependencies usually hide. It does not suggest checking one service and moving on. It tells teams to search code, configuration, and surrounding infrastructure for references to the v1 endpoints, including backend services, workers, serverless functions, webhooks, CI/CD scripts, integration tests, SDK wrappers, and third-party tools or libraries where authentication was configured.
That is why this becomes billable work in the real world. OAuth logic rarely stays neatly contained in one module. Over time it gets copied into install callbacks, refresh jobs, uninstall handlers, support scripts, and monitoring checks. Some of it may sit inside wrappers nobody has reviewed for years because the old endpoints kept working. HubSpot's versioning documentation helps explain the pattern: older semantic-versioned APIs remain available at their previous URLs, even though new REST APIs now follow the /YYYY-MM/ date-based format.
So the real task is not just future-proofing. It is finding every place where the old flow still assumes secrets can safely travel in the URL path or query string. If that inventory is skipped, teams often update the obvious token exchange and leave behind a forgotten revoke call, an introspection lookup, or a support utility that still uses the legacy pattern.
What a proper cleanup includes
HubSpot's own migration path maps quite cleanly to a real client project. In practice, that usually means work like this:
- Inventory every reference to
/oauth/v1/token,/oauth/v1/access-tokens, and/oauth/v1/refresh-tokensacross production code, scheduled jobs, serverless functions, webhooks, deployment scripts, tests, and wrappers. - Replace authorization-code exchanges with
POST /oauth/2026-03/token. HubSpot's current token guide shows the request body carryingclient_id,client_secret, the one-timecode,grant_type=authorization_code, and theredirect_uri. - Replace refresh logic with the same
POST /oauth/2026-03/tokenendpoint, usinggrant_type=refresh_token. HubSpot also states that access tokens are short-lived, expiring after 30 minutes, withexpires_indefining the lifetime in seconds. - Replace token metadata lookups with
POST /oauth/2026-03/token/introspect. The request body should includeclient_id,client_secret,token_type_hint, and the relevant token, instead of placing sensitive values in the URL path. - Replace uninstall or disconnect revocation flows. The old
DELETE /oauth/v1/refresh-tokens/{token}call becomesPOST /oauth/2026-03/token/revoke, with the token sent in a form-encoded body together withclient_id,client_secret, andtoken_type_hint. - Standardize error handling around
erroranderror_description. HubSpot's migration guide says those fields should drive conditional logic and user-facing messages, whilestatusandmessagecan still be logged for backward compatibility. - Test the full flow in a non-production environment, including authorization-code exchange, refresh, introspection, and revoke paths. HubSpot specifically recommends verifying that client IDs, client secrets, authorization codes, and tokens no longer appear in URLs, logs, or telemetry.
There is one useful narrowing point in HubSpot's guidance: the OAuth install URL, consent page, and requested scopes do not change. The migration is centered on the backend token and token-metadata endpoints your app calls after installation. That limits the blast radius, but it does not make the work trivial.
Where platform versioning widens the scope
If the setup is just an external integration, the OAuth flow may be most of the job. But many teams also maintain project-based HubSpot apps, and that pulls HubSpot's platform versioning into the conversation. According to HubSpot's versioning documentation, new API and platform versions are released every March and September. A version is Current for six months, then Supported, and then Unsupported 18 months after general availability. Once a project version becomes Unsupported, uploads fail.
That matters because OAuth cleanup often sits beside overdue platform maintenance. HubSpot says you can check a project's platform version in the top-level hsproject.json file through the platformVersion field. If an app is already on 2025.2, the path is to update platformVersion to 2026.03 and run hs project upload. If a project is still on 2023.1, 2023.2, or 2025.1, HubSpot's guidance is to run hs project migrate and follow the prompts so components move to 2026.03.
The dates matter here as well. HubSpot's versioning page says platform version 2025.1 will be deprecated on August 1, 2026. It also warns that certain legacy apps migrated to platform version 2026.03 cannot be downgraded afterward. That is another reason to treat this as scoped migration work rather than opportunistic maintenance. Once auth changes and platform-version changes overlap, a deliberate plan is much cheaper than a chain of hurried fixes.
Why this turns into a paid cleanup project
The commercial logic is straightforward. HubSpot has published a hard cutoff date, documented a security reason for moving away from the old endpoints, and laid out a migration path that touches code, configuration, testing, and operations. That is exactly when tolerated integration debt becomes planned remediation work.
For GrN, the practical engagement is clear: inventory every HubSpot touchpoint, replace legacy OAuth flows with the 2026-03 endpoints, review where tokens or secrets may have leaked into logs or telemetry, rotate or revoke affected credentials where appropriate, update project versions where HubSpot apps are involved, and add validation scripts that prove the old endpoints are gone. Done properly, that reduces current exposure and removes a very predictable source of authentication failures before February 16, 2027.
Need help with this kind of work?
Discuss your HubSpot cleanup project Get in touch with Greg.