Skip to main content

Initiating OAuth access is the first step towards allowing users to install your app in their HubSpot account(s).

Before you can initiate an OAuth connection, you have to create a HubSpot app. The client ID that you'll need to include in the authorization URL can be found in the app settings. Navigate to these settings by clicking the name of your app from your developer account dashboard.

To initiate OAuth access, you'll need to send HubSpot users to your authorization URL. Use the query parameters detailed below to identify your app and outline its required scopes to users who land on the authorization page.

Users must be signed into HubSpot to grant your app access. Any user that isn't logged into HubSpot will be directed to a login screen before being directed back to the authorization page. The authorization screen will show the details for your app and the permissions being requested (based on the scopes you include in the URL). Users will have the option to select the Hub ID for the account they wish to grant access to.

After the user grants access, they will be redirected to the specified redirect_uri. A code query parameter will be appended to the URL, which you'll use to get an access token from HubSpot.

Requirements
Auth Methods

Private apps

OAuth

Parameters
client_id*

Query param

The client ID from your app settings.

redirect_uri*

Query param

The URL visitors will be redirected to after granting access to your app. Please note: For security reasons, this URL must use https in production. When testing using localhost, http can be used. Also, you must use a domain, as IP addresses are not supported.

scope*

Query param

A space-separated set of scopes that your app will need access to. Scopes listed in this parameter will be treated as required for your app, and the user will see an error if they select an account that does not have access to the scope you've included.Any scopes that you have checked in your app settings will be treated as required scopes, and you'll need to include any selected scopes in this parameter or the authorization page will display an error.See below for more details about which APIs are accessed by specific scopes.

optional_scope

Query param

A space separated set of scopes that are optional for your app. Optional scopes will be automatically dropped from the authorization request if the user selects a HubSpot account that does not have access to that tool (such as requesting the social scope on a CRM only portal). If you're using optional scopes, you will need to check the access token or refresh token to see which scopes were granted. See the table below for more details about scopes.

state

Query param

A string value that can be used to maintain the state of the user when they are redirected back to your application. If this parameter is included in the authorization URL, the value will be included in a state query parameter when the user is directed to the redirect_uri.

Response

Show more

GET

/oauth/v1/access-tokens/:token

Get the meta data for an access token. This can be used to get the email address of the HubSpot user that the token was created for, as well as the Hub ID that the token is associated with.

Note: HubSpot access tokens will fluctuate in size as a result of changes to the data encoded in the tokens. It's recommended that you allow for tokens to be up to 512 characters to account for any future changes to token length.

Requirements
Auth Methods

Private apps

OAuth

Parameters
token*

Path param

The access token that you want to get the information for.

Response

Show more

GET

/oauth/v1/refresh-tokens/:token

Get the meta data for a refresh token. This can be used to get the email address of the HubSpot user that the token was created for, as well as the Hub ID that the token is associated with.

Note: For a more elaborate walkthrough on initiating Oauth, visit this link.

Requirements
Auth Methods

Private apps

OAuth

Parameters
token*

Path param

The refresh token that you want to get the information for.

Response

Show more

POST

/oauth/v1/token

Use the code you get after a user authorizes your app to get an access token and refresh token. The access token will be used to authenticate requests that your app makes. Access tokens are short lived, so you can use the refresh token to get a new access token when the current access token expires.

Note: HubSpot access tokens will fluctuate in size as a result of changes to the data encoded in the tokens. It's recommended that you allow for tokens to be up to 512 characters to account for any future changes to token length.

Requirements
Auth Methods

Private apps

OAuth

Parameters
grant_type*

Body param

The grant type of the request, must be authorization_code for the initial request to get the access and refresh tokens.

client_id*

Body param

The Client ID of your app.

client_secret*

Body param

The Client Secret of your app.

redirect_uri*

Body param

The redirect URI that was used when the user authorized your app. This must exactly match the redirect_uri used when initiating the OAuth 2.0 connection.

code*

Body param

The code parameter returned to your redirect URI when the user authorized your app.

Response

Show more

POST

/oauth/v1/token

Use a previously obtained refresh token to generate a new access token. Access tokens are short lived; you can check the expires_in parameter when generating an access token to determine its lifetime (in seconds). If you need offline access to HubSpot data, store the refresh token you get when initiating your OAuth integration and use it to generate a new access token once the initial one expires.

Note: HubSpot access tokens will fluctuate in size as a result of changes to the data encoded in the tokens. It's recommended that you allow for tokens to be up to 512 characters to account for any future changes to token length.

Requirements
Auth Methods

Private apps

OAuth

Parameters
grant_type*

Body param

The grant type of the request, must be refresh_token when refreshing an access token.

client_id*

Body param

The client ID of your app.

client_secret*

Body param

The client secret of your app.

refresh_token*

Body param

The refresh token obtained when initially authenticating your OAuth integration.

Response

Show more

DELETE

/oauth/v1/refresh-tokens/:token

Deletes a refresh token. You can use this to delete your refresh token if a user uninstalls your app.

Note: This will only delete the refresh token. Access tokens generated with the refresh token will not be affected.

Note: This will not uninstall an application from a HubSpot account or inhibit data syncing between an account and a connected application.

Requirements
Auth Methods

Private apps

OAuth

Parameters
token*

Path param

The refresh token that you want to delete.

Response

Show more