Initiate an Integration with OAuth 2.0

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.


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.

  • 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: There will be limited functionality with the Analytics API without a paid Marketing subscription.
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 Basic, Professional, or Enterprise Marketing
e-commerce Products API and Line Items API Any account with Sales Professional 
files File Manager API Any Marketing or CRM account
forms Forms API - Note: Forms access also requires the contacts scope. Basic, Professional, or Enterprise Marketing
hubdb HubDB API Basic, Professional, or Enterprise Marketing with Website add on
integration-sync Ecommerce Bridge API Any Marketing or CRM account
social Social Media API Basic, Professional, or Enterprise Marketing
tickets Tickets API Any account with the Service Hub
timeline Timelines API Any Marketing or CRM account
transactional-email Transactional Email API Basic, Professional, or Enterprise Marketing with Transactional Email add on