Reminder: As of August 9th, the demo API key will only be allowed to make GET requests. Please see the announcement for more details.

Initiate an Integration with OAuth 2.0

Last updated June 25, 2019

Initiating OAuth access is the first step for having users install your app in their HubSpot account. In order to initiate OAuth access for your HubSpot App, you'll first need to send a HubSpot user to an authorization page, where that user will need to grant access to your app.  When your app sends a user to that authorization page, you'll use the query parameters detailed below to identify your app, and to also specify the scopes that your apps requires.

Initiating an OAuth connection requires that you create a HubSpot app.  The client ID that you'll need to include in the authorization URL can be found in the settings for the app, which you can get to by clicking the name of your app from your developer dashboard.

Users must be signed into HubSpot to grant access, so any user that is not 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 redirect_uri that you specified, with a code query parameter appended to the URL.  You'll use that code 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 that you want the visitor 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.


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.

  • 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 COS APIs, Calendar API, Email and Email Events APIs Marketing 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
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