Skip to main content

Before you can start using OAuth with HubSpot, you'll need to have:

*You must be a Super Admin to install an app in a HubSpot account


HubSpot supports the OAuth 2.0 Authorization Code grant type, which can be broken down into four basic steps:

  1. Your app opens a browser window to send the user to the HubSpot OAuth 2.0 server
  2. The user reviews the requested permissions and grants the app access
  3. The user is redirected back to the app with an authorization code in the query string
  4. The app sends a request to the OAuth 2.0 server to exchange the authorization code for an access token

Note: All code examples in this guide are written in JavaScript (Node.js)

If this is your first time using OAuth authentication with HubSpot's APIs, we strongly recommend checking out the OAuth 2.0 Quickstart App, written in Node.js. This sample app is designed to get you started using OAuth 2.0 as quickly as possible by demonstrating all the steps outlined below in Getting OAuth 2.0 tokens.

When sending a user to HubSpot's OAuth 2.0 server, the first step is creating the authorization URL. This will identify your app and define the resources (scopes) it's requesting access to on behalf of the user. The query parameters you can pass as part of an authorization URL are shown below. For more detailed information on this step, read the reference doc.

ParameterRequired?DescriptionExample
client_idYesThe client ID identifies your app. Find it on your app's settings page.7fff1e36-2d40-4ae1-bbb1-5266d59564fb
scopeYesThe scopes your application is requesting, separated by URL-encoded spaces.contacts%20social
redirect_uriYesThe URL that the user will be redirected to after they authorize your app for the requested scopes. For production applications, https is required.https://www.example.com/auth-callback
optional_scopeNoThe scopes that are optional for your app, and will be dropped if the selected HubSpot portal does not have access to those productsautomation
stateNoA unique string value that can be used to maintain the user's state when they're redirected back to your app.WeHH_yy2irpl8UYAvv-my

Once you've created your URL, start the OAuth 2.0 process by sending the user to it.

Using a server-side redirect:

Using an HTML link:

Some apps may need to redirect the user to different locations. For example, an app may wish to redirect users to different subdomains of their integration (e.g. userA.integration.com and userB.integration.com). To do so, use the state parameter to encode more information about the user state:

1. Generate and store a nonce value for the state parameter.

2. Store the user's state in a local datastore using the nonce as its key.

3. Include the nonce value as the state parameter in the authorization URL.

4. When the user authenticates and is redirected to your redirect URL, validate the state parameter and use it as the key to retrieve the user state that was stored.

5. From there, redirect the user as needed (e.g. redirecting again to a user specific URL).

HubSpot displays a consent window to the user showing the name of your app and a short description of the HubSpot API services it's requesting permission to access. The user can then grant access to your app.

[Example] Install Screen

Note: The user installing the app must have access to all requested scopes. If they don't have the required access, the installation will fail and they will be directed to an error page. If a user sees this permissions error page, they'll need to have a Super Admin install the app.

Your application doesn't do anything at this stage. Once access is granted, the HubSpot OAuth 2.0 server will send a request to the callback URI defined in the authorization URL.

When the user has completed the consent prompt from Step 2, the OAuth 2.0 server sends a GET request to the redirect URI specified in your authentication URL. If there are no issues and the user approves the access request, the request to the redirect URI will be returned with a code query parameter attached. If the user doesn't grant access, no request will be sent.

After your app receives an authorization code from the OAuth 2.0 server, it can exchange that code for an access and refresh token by sending a URL-form encoded POST request to https://api.hubapi.com/oauth/v1/token with the values shown below. For more detailed information on this step, take a minute to read this reference doc.

ParameterDescriptionExample
grant_typeMust be authorization_codeauthorization_code
client_idYour app's client ID7fff1e36-2d40-4ae1-bbb1-5266d59564fb
client_secretYour app's client secret7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d
redirect_uriThe redirect URI from when the user authorized your apphttps://www.example.com/auth-callback
codeThe authorization code received from the OAuth 2.0 server5771f587-2fe7-40e8-8784-042fb4bc2c31

The body of the token response will be JSON data with the form:

Note: The access token will expire after the number of seconds given in the expires_in field of the response, currently 30 minutes. For information on getting a new access token, see Refreshing OAuth 2.0 tokens.

Once the authorization code flow is completed, your app is authorized to make requests on behalf of the user. To do this, provide the token as a bearer token in the Authorization HTTP header. Specific details can be found in the reference doc.

OAuth access tokens expire periodically. This is to make sure that if they're compromised, attackers will only have access for a short time. The token's lifespan in seconds is specified in the expires_in field when an authorization code is exchanged for an access token.

Your app can exchange the received refresh token for a new access token by sending a URL-form encoded POST request to https://api.hubapi.com/oauth/v1/token with the values below. For more detailed information on this step, check out the reference doc.

ParameterDescriptionExample
grant_typeMust be refresh_tokenrefresh_token
client_idYour app's client ID7fff1e36-2d40-4ae1-bbb1-5266d59564fb
client_secretYour app's client secret7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d
redirect_uriThe redirect URI from when the user authorized your apphttps://www.example.com/auth-callback
refresh_tokenThe refresh token received when the user authorized your appb9443019-30fe-4df1-a67e-3d75cbd0f726

The body of the token response will be JSON data with the form:

The new access token can then be used to make calls on behalf of the user. When the new token expires, you can follow the same steps again to retrieve a new one.