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.
On February 16, 2027, HubSpot will deprecate the legacy OAuth v1 endpoints in favor of the latest OAuth API (2026-03). The latest version provides stronger security guarantees and standardized error responses, while still preserving the same core OAuth 2.0 functionality.
If you received an email or changelog notification about the OAuth v1 API sunset, your app has recently used one or more of the deprecated v1 endpoints and must migrate to the latest OAuth API to avoid authentication failures after the sunset date.
This guide walks through how to update your app from the legacy v1 endpoints over to the latest OAuth endpoints in preparation for the upcoming sunset.
1. Review your current OAuth usage
To start, search your codebase, configuration, or any other infrastructure for your app for references to the following endpoints:
/oauth/v1/token/oauth/v1/access-tokens/oauth/v1/refresh-tokens
You may want to include the following sources in your search:
- Backend services and workers
- Serverless functions and webhooks
- CI/CD scripts, integration tests, and SDK wrappers
- Any third-party tools or libraries where you’ve configured authentication
If you’re maintaining an app on the HubSpot marketplace, you should have received a HubSpot email notification that lists the IDs of the apps that recently called any v1 endpoints.
For each code path that invokes a v1 endpoint, document whether your code uses an authorization code or refresh token grant, and how it currently handles errors. You can then use the results of your review to inform the updates in the following steps.
2. Update token exchange
For any references in your app’s code that handles the authorization code flow via a POST request to the /oauth/v1/token endpoint, swap the endpoint over to /oauth/2026-03/token instead.
Ensure all parameters are provided as form-encoded body fields, not as query parameters.
The tabs below provide an example cURL request using the v1 endpoint compared to the equivalent latest endpoint (2026-03):
Before (v1)
After (2026-03)
curl --request POST \
--url https://api.hubapi.com/oauth/v1/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code&code=AUTH_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
curl --request POST \
--url https://api.hubapi.com/oauth/2026-03/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code&code=AUTH_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
3. Update refresh token logic
Update any refresh token logic that handles refresh token logic via a POST request to the /oauth/v1/token endpoint over to use the /oauth/2026-03/token endpoint instead.
Ensure all parameters are provided as form-encoded body parameters. You should also confirm that your code uses the new access_token property returned by this endpoint, and use the expires_in field to determine the token lifetime.
Consult the tabs below for to compare an example cURL request using the v1 endpoint against the equivalent latest endpoint (2026-03):
Before (v1)
After (2026-03)
curl --request POST \
--url https://api.hubapi.com/oauth/v1/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
curl --request POST \
--url https://api.hubapi.com/oauth/2026-03/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
GET requests for the v1 token metadata endpoints listed below:
/oauth/v1/access-tokens/{token}/oauth/v1/refresh-tokens/{token}
These requests should be migrated to be POST requests to the token introspect endpoint at /oauth/2026-03/token/introspect.
Instead of providing the token in the path in the v1 endpoints, send it in the request body instead, along with any required client credentials.
Additionally, unlike the /oauth/2026-03/token endpoints, which return an identical response to the /oauth/v1/token endpoint, the introspect endpoints for /oauth/2026-03/token/introspect returns a new model, detailed below:
Refresh token model
The table below shows the equivalent fields returned in the new response from the /oauth/2026-03/token/introspect endpoint for a refresh token compared to the v1 equivalent:
| Field | v1 model | 2026-03 model |
|---|
tokenType | "refresh" | "Bearer" |
tokenUse | (absent) | "refresh_token" |
appId | (absent) | Integer |
active | (absent) | Boolean |
Access token model
| Field | v1 model | 2026-03 model |
|---|
clientId | (absent) | String |
tokenType | "access" (default) | "Bearer" |
tokenuse | (absent) | "access_token" |
active | (absent) | Boolean |
Request fields
When making a POST request to the /oauth/2026-03/token/introspect endpoint, the request body is form-urlencoded with the following fields:
| Field | Type | Description |
|---|
client_id | String | Your app’s client ID |
client_secret | String | Your app’s client secret |
token_type_hint | String | Either “access_token” or “refresh_token” |
token | String | The refresh token or access token value, depending on which token you’re introspecting. |
cURL request to the introspect endpoint:
curl --request POST \
--url https://api.hubapi.com/oauth/2026-03/token/introspect \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'client_id=<string>' \
--data 'client_secret=<string>' \
--data 'token=<string>' \
--data 'token_type_hint=<string>'
5. Update token revocation logic
If your app had any explicit logic to revoke refresh tokens when users uninstall or disconnect your app, you must migrate from the v1 DELETE endpoint to the new 2026-03 revoke endpoint.
Replace any previous DELETE requests to /oauth/v1/refresh-tokens/{token} with a POST request to /oauth/2026-03/token/revoke.
Ensure that you pass the refresh token in a URL-encoded request body.
6. Standardize your error handling
With the 2026-03 version of the OAuth API, error responses include both standard OAuth and HubSpot-specific fields:
- Standard:
error, error_description
- HubSpot-specific:
status, message
The recommended approach is to switch your error handling to rely on error and error_description for conditional logic and displaying user-facing messages.
From there, you can optionally continue logging or monitoring the status and message fields, since they’ll remain available for backward compatibility.
These changes to error handling will make your app more portable across OAuth providers and more resilient to future internal changes to HubSpot-specific error fields.
7. Test and deploy
Before rolling changes to production, it’s recommended that you do the following:
- Test in a non-production environment: complete a full OAuth install flow, by performing a authorization code exchange, token refresh, and test out any paths that introspect or revoke tokens.
- Verify logs and telemetry: confirm that your app’s client ID, client secret, authorization code, and tokens no longer appear in URLs or logs.
- Monitor rollout: watch for increased
4xx responses around OAuth endpoints. Pay particular attention to the new error payload and ensure your error handling correctly parses the error and error_description.
The latest OAuth endpoints are now available and recommended for all new development. The legacy OAuth v1 API endpoints will remain active until February 16, 2027. After this date, calls to the v1 endpoints will begin returning errors, and any integrations that have not migrated may experience authentication failures and functionality for app users.
Other considerations
Keep the following points in mind as you plan your migration to the latest version of the OAuth API:
- The OAuth install URL, consent page, and any scopes you request are unchanged. The migration updates only the backend token and token metadata endpoints your app calls after a user installs the app.
- If you’re using the v3 OAuth API:
- Confirm all sensitive fields are passed in the request body and not in the URL. Requests that include sensitive data in the URL will return an error, even if the same data is provided in the body.
- Update your error handling to rely on
error and error_description if you haven’t already.
- It’s recommended that you update your API paths to
/oauth/2026-03 to align with HubSpot’s broader date-based API versioning release.
Further resources
For more information, check out the following resources:
