HubSpot Developer Changelog

New OAuth v3 API Endpoints and Standardized Error Responses

We are enhancing the security and compliance standards of our Developer Platform with the release of OAuth v3 API endpoints and updated error response formatting. 

What's Changing?

 

New Oauth v3 Token Endpoints

To align with OAuth 2.0 security best practices, we have introduced two new v3 OAuth API endpoints designed to keep sensitive credentials out of server logs and browser histories. 

  • POST /v3/token: Handles authorization code and refresh token requests.
  • POST /v3/introspect: Performs token introspection, replacing the separate v1 path-based token metadata for access tokens and refresh tokens. 

Standardized OAuth Error Responses

We are updating our OAuth error responses to comply with RFC 6749. This ensures better compatibility with third-party OAuth libraries and simplifies troubleshooting. 

What’s changed? Previously, responses included HubSpot-specific fields (status and message). Responses now include the standard error and error_description fields.

Example Response:

// Example Response { "error": "invalid_grant", "error_description": "refresh token is invalid, expired or revoked", "status": "BAD_REFRESH_TOKEN", "message": "refresh token is invalid, expired or revoked" }

Existing fields (status, message) remain for backward compatibility, so existing error handling will continue to function as is.

Important Note: These responses will be reflected in both the v1 and v3 OAuth API endpoints.

 

What does this mean for developers?

 

  • Adopt v3: Start targeting /v3/token and /v3/introspect for all new developments. 
  • Update Request Logic: Ensure your application sends credentials in the request body, never in the URL. 
  • Error Handling: You can now update your client-side error handling to parse standard OAuth error fields. 

Important note: There are no changes to the scope, app settings, or the OAuth install process. 

Sunset Notice for v1 OAuth API Endpoints

The v1 OAuth API endpoints will remain operational for now, but they are officially deprecated. We will provide a detailed sunset timeline later in Q1 2026. Please subscribe to the HubSpot Developer Changelog to ensure you receive this update.

 

When is it happening?

 

The v3 OAuth API endpoints are now available for use, and the error standardization is now reflected in both the v3 and v1 OAuth API endpoints.

Questions or comments? Join us in the developer forums for a peer-to-peer discussion.