There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Initiate an integration with OAuth 2.0

Last updated August 23, 2023

https://app.hubspot.com/oauth/authorize

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

Initiating OAuth access

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.

Required parameters How to use Description
Client ID client_id=x
Used in the URL		 The client ID from your app settings.
Redirect URI redirect_uri=x
Used in the URL		 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 scope=x%20x 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 parameters How to use Description
Optional scopes &optional_scope=x%20x 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 &state=y 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.

Scopes

Each scope provides access to a set of HubSpot APIs.  Certain HubSpot accounts may only have access to specific APIs, as noted below. If your app can work with multiple types of HubSpot accounts, you can use the optional_scope parameter to include any scopes you work with that only apply to marketing accounts, so that customers using CRM accounts can still authorize your app.  Your app will be responsible for checking for and handling any scopes that you didn't get authorized for.

You can see a detailed breakdown for which APIs are supported for each product level on our APIs by Product Tier page.

Notes:
  • Developer portals will not have access to any of these scopes, and cannot be authorized with an app. You will need to create a test portal to test authorization.
  • Due to the interconnected nature of the tools, both the contacts and forms scopes are required to access the Forms API.

 

scope provides access to Account types that can access the scope
automation Workflows API Professional or Enterprise Marketing
business-intelligence Analytics API
Note: Access to specific data will depend on the subscription that the HubSpot account has. See the Analytics API overview for more details.		 Any Marketing or CRM account.
contacts Contacts, Companies, and Deals, along with the associated property APIs, Engagements API, Owners API Any Marketing or CRM account
content All CMS APIs, Calendar API, Email and Email Events APIs Marketing Professional, or Enterprise 
conversations.visitor_
identification.tokens.create

(This is a single value, broken on to two lines for formatting.)		 Fetch identification tokens for authenticated website visitors interacting with the HubSpot chat widget. Professional or Enterprise 
e-commerce Products API and Line Items API Any account with Sales Professional 

Note: A user must be assigned a paid Sales Hub seat to authorize this scope.
files File Manager API Any Marketing or CRM account
forms Forms API - Note: Forms access also requires the contacts scope. Any Marketing account
hubdb HubDB API Professional, or Enterprise Marketing with Website add on
integration-sync Ecommerce Bridge API Any Marketing or CRM account
sales-email-read Engagements API*
Note: This scope is required to get the content of email engagements. See the Engagements overview for more details.		 Any Sales Hub account
social Social Media API Marketing Professional, or Enterprise
tickets Tickets API Any account with the Service Hub
timeline Timelines API Any Marketing or CRM account
transactional-email Transactional Email API Professional, or Enterprise Marketing with Transactional Email add on

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example Authorization URL: Sending a user to this URL will ask the user to approve access to contacts and workflows: https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/ If they grant access, the user would be redirected to this URL: https://www.example.com/?code=xxxx If there are any problems with the authorization, you'll get the error parameters instead of the code: https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error