OAuth Quickstart Guide
Before you get started
Before you can start using OAuth with HubSpot, you'll need to have:
- A developer account
- An app associated with your developer account
- A HubSpot account* to install your app in (you can use an existing account or create a test account)
*You must be a Super Admin to install an app in a HubSpot account
How it works
HubSpot supports the OAuth 2.0 Authorization Code grant type, which can be broken down into four basic steps:
- Your app opens a browser window to send the user to the HubSpot OAuth 2.0 server
- The user reviews the requested permissions and grants the app access
- The user is redirected back to the app with an authorization code in the query string
- The app sends a request to the OAuth 2.0 server to exchange the authorization code for an access token
In this guide
- Quickstart App: A Node.js demo app that authenticates with HubSpot's OAuth 2.0 server
- Getting OAuth 2.0 tokens: How to authorize your app with users
- Using OAuth 2.0 tokens: How to make queries with a token
- Refreshing OAuth 2.0 tokens: How to use the refresh token provided by HubSpot
Note: All code examples in this guide are written in JavaScript (Node.js)
Quickstart app
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.
Getting OAuth 2.0 tokens
Step 1: Create the authorization URL and direct the user to HubSpot's OAuth 2.0 server
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.
Parameter | Required? | Description | Example |
---|---|---|---|
client_id |
Yes | The client ID identifies your app. Find it on your app's settings page. |
|
scope |
Yes | The scopes your application is requesting, separated by URL-encoded spaces. |
|
redirect_uri |
Yes | The URL that the user will be redirected to after they authorize your app for the requested scopes. For production applications, https is required. |
|
optional_scope |
No | The scopes that are optional for your app, and will be dropped if the selected HubSpot portal does not have access to those products |
|
state |
No | A unique string value that can be used to maintain the user's state when they're redirected back to your app. |
|
Once you've created your URL, start the OAuth 2.0 process by sending the user to it.
Examples
Using a server-side redirect:
Using an HTML link:
Encoding an additional redirect user state
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).
Step 2: HubSpot prompts user for consent
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.
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.
Step 3: Handle the OAuth 2.0 server response
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.
Example:
Step 4: Exchange authorization code for tokens
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.
Parameter | Description | Example |
---|---|---|
grant_type |
Must be authorization_code |
authorization_code |
client_id |
Your app's client ID | 7fff1e36-2d40-4ae1-bbb1-5266d59564fb |
client_secret |
Your app's client secret | 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d |
redirect_uri |
The redirect URI from when the user authorized your app | https://www.example.com/auth-callback |
code |
The authorization code received from the OAuth 2.0 server | 5771f587-2fe7-40e8-8784-042fb4bc2c31 |
Example:
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.
Using 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.
Example:
Please note:access tokens reflect the scopes requested from the app and do not reflect the permissions or limitations of what a user can do in their HubSpot account. For example, if a user has permissions to view only owned contacts but authorizes a request for the crm.objects.contacts.read
scope, the resulting access token can view all contacts in the account and not only those owned by the authorizing user.
Refreshing OAuth 2.0 tokens
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.
Parameter | Description | Example |
---|---|---|
grant_type |
Must be refresh_token |
refresh_token |
client_id |
Your app's client ID | 7fff1e36-2d40-4ae1-bbb1-5266d59564fb |
client_secret |
Your app's client secret | 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d |
redirect_uri |
The redirect URI from when the user authorized your app | https://www.example.com/auth-callback |
refresh_token |
The refresh token received when the user authorized your app | b9443019-30fe-4df1-a67e-3d75cbd0f726 |
Example:
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.
Related docs
Thank you for your feedback, it means a lot to us.