OAuth 2.0 Overview

Authentication for your integration starts with creating an app in a HubSpot Developer account. You'll use the Client ID and Client Secret from that app to initiate the OAuth handshake between HubSpot and your integration.


OAuth 2.0 allows a user to authorize your app to work with specific tools in their HubSpot account, designated by the authorization scopes you set.  You can find more details about the available scopes and the tools they provide access to here.

Connecting your app to HubSpot using OAuth 2.0

 There are 4 main steps to connecting your integration to a customers HubSpot account using OAuth:

  1. Build the authentication URL for your app, and send the HubSpot user to that URL.  The user will be presented with a screen that allows them to grant access to your integration.  If a user has multiple HubSpot accounts, they'll have the option to choose which account they're granting access for.
  2. After the user grants access, they'll be returned to your app, with a code appended to the URL. Use that code and your Client Secret to get an access_token and refresh_token.
  3. Use that access_token to authenticate any API calls that you make for that HubSpot account.
  4. Once that access_token expires, use the refresh_token from Step 2 to generate a new access_token

Differences from OAuth 1

If you've worked with the previous version of Oauth, there are a few things to keep in mind when updating to Oauth 2.0

  • Your existing HubSpot apps and Client IDs can be used with OAuth 2.0. However, access and refresh tokens from OAuth1 are incompatible with OAuth 2.0, so you will need to re-authenticate existing users.
  • You no longer need to specify the Hub ID in the URL you send the user to to authorize your app.  Users will have the ability to select which HubSpot account they want to authenticate on the HubSpot authentication screen.
  • After authorizing your app, instead of getting an access_token and refresh_token, you'll get a code.  You use that code, along with your Client Secret from your app settings, to generate the access_token and refresh_token
  • When making API calls with OAuth 2.0 access_tokens, the token gets passed in an Authorization header, and not in the URL as a query parameter.

Docs for this section or API