Initiate an Integration with Oauth 2.0

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

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. For security reasons, this URL must use https.
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.

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.

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.
  • Only paid Marketing subscriptions will have API access to the scopes and tools listed below for Marketing accounts.  Marketing Free accounts will not have API access to any of the Marketing-only scopes.

 

scope provides access to Account types that can access the scope
contacts Contacts, Companies, and Deals, along with the associated property APIs, Engagements API, Owners API Marketing and CRM
content All COS APIs, Calendar API, Email and Email Events APIs Marketing
reports Keywords API Marketing
social Social Media API Marketing
automation Workflows API Marketing
timeline Timelines API Marketing and CRM
forms Forms API Marketing
files File Manager API Marketing and CRM
hubdb HubDB API Marketing with Website add on
transactional-email Transactional Email API Marketing with Transactional Email add on