HubSpot OAuth BAD_REFRESH_TOKEN — What it means & how to fix it

"status": "BAD_REFRESH_TOKEN", "message": "missing or invalid refresh token."

If you integrate with HubSpot's APIs using OAuth, you'll encounter this error eventually.

This article shows you how to detect and resolve the issue, and provides proven tactics to minimize HubSpot refresh token surprises in production.

Spot the error

When your backend POSTs to https://api.hubapi.com/oauth/v1/token to swap a HubSpot OAuth refresh token for a new access token, HubSpot can answer with HTTP error code 400:

{
  "status": "BAD_REFRESH_TOKEN",
  "message": "missing or invalid refresh token"
}
  

That single JSON payload means the refresh token is unusable. Sometimes HubSpot also identifies this error with different error codes like invalid_grant or unauthorized.

Retrying the same request will keep failing until the root cause is fixed.

Why was the refresh token revoked?

HubSpot maintains several reasons why they revoke refresh tokens.

Most common: User revoked access

‍If you encounter the issue during normal operations, the most likely cause is user action.

The end-user removed your application from their HubSpot account, which immediately invalidates all associated tokens. This can happen through:

• Uninstalling the app from the HubSpot portal
• Manually revoking access in account settings
• Admin removing the app from the organization

App uninstallation

‍When a user uninstalls your app from their HubSpot portal, all refresh tokens associated with that app are immediately revoked.

Access token limit reached

‍HubSpot has limits on the number of active refresh tokens per app per user. When the limit is exceeded, older tokens may be automatically invalidated.

Token expiration

‍While HubSpot refresh tokens are long-lived, they can still expire under certain conditions:

• Extended periods of inactivity
• Security policies triggered by HubSpot
• App configuration changes

Scope changes

‍If the app's scopes are modified after the initial authorization, existing refresh tokens may become invalid and require re-authorization.

Client credentials mismatch

‍Using incorrect client ID or client secret when refreshing tokens will result in BAD_REFRESH_TOKEN errors.

Other undocumented reasons

‍HubSpot occasionally flags tokens for security heuristics that aren't published. Bugs, refresh token race conditions, and other edge cases could also lead to your token getting revoked.

Ultimately, it's impossible to know exactly why the refresh token was revoked.

In our experience, a rate ~1% of revoked tokens per month is normal.

How to fix it

1. Check if user revoked access

The most common cause is that the user manually revoked access or uninstalled the app. There's no way to revive a revoked token.

2. Not a user action? Ask your users to re-authenticate

A HubSpot refresh token revoked event is final. There's no endpoint to revive it.

Show an in-app prompt and ask the user to run the OAuth flow again. Persist the new HubSpot OAuth refresh token that HubSpot returns.

3. Verify client credentials

Double-check that you're using the correct client_id and client_secret when making the refresh request. Mismatched credentials will always result in BAD_REFRESH_TOKEN errors.

How to prevent refresh token issues

A few engineering habits go a long way:

• Refresh on a schedule
  ‍Touch the token regularly so it never sits idle for extended periods‍
• Discard stale access tokens
  ‍Once you refresh, throw the old HubSpot access token away. Re-using it can trip HubSpot's anomaly detection‍
• Store any new refresh token HubSpot sends back
  ‍Some APIs rotate them silently‍
• Monitor BAD_REFRESH_TOKEN spikes
  ‍Retry once; if it fails again, mark the account "re-auth required" and alert the user. If a large number of access tokens fail to refresh you need to take a closer look.
• Handle app uninstallation gracefully
  ‍Set up webhooks or monitoring to detect when your app is uninstalled so you can clean up associated data‍
• Implement proper error handling
  ‍Distinguish between different error types to provide appropriate user messaging‍

Skip the headache, let Nango refresh for you

Nango's open-source API auth offers:

• 500+ pre-built OAuth flows, including full support for all HubSpot APIs
• Automatic OAuth access token refreshing and rotation
• Webhooks when a refresh token is revoked, so you can warn the user instantly
• Built-in error handling for all OAuth edge cases

Focus on product features and Nango handles the token lifecycle.