Working with OAuth

OAuth is a secure means of authentication that uses authorization tokens rather than a password to connect your app to a user account. Initiating OAuth access is the first step towards allowing users to install your app in their HubSpot account(s).

Note for all app builders: Any app designed for installation by multiple HubSpot accounts or listing on the App Marketplace must use OAuth. If you use an API key, your app listing will be rejected. 

Recommended resources
  • The OAuth Quickstart Guide will get you up and running with a working example app.
  • This HubSpot Academy tutorial provides a quick introduction on using OAuth with HubSpot, including a breakdown of the HubSpot-OAuth flow and how to refresh an access token.

Initiating an integration with OAuth 2.0

1. The first step for using OAuth is to create an app in a HubSpot developer account. When you do this, you'll find the client ID and client secret for your app on the Auth page of your app settings.

MyHubSpotApp

 

2. Use the client ID and client secret, along with the query parameters and scopes outlined below, to build your authorization URL. 

3. Send users installing your app to the authorization URL, where they'll be presented with a screen that allows them to select an account (if they have multiple accounts) and grant access to your integration. After granting access, they'll be redirected back to your application via a redirect_url, which will have a code query parameter appended to it. You'll use that code and the client secret to get an access_token and refresh_token from HubSpot.

Example authorization URL

https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/

Example redirect URL

https://www.example.com/?code=xxxx

Example error

https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error

 

4. Use the access_token to authenticate any API calls made for that HubSpot account.

5. Once the access_token expires, use the refresh_token from Step 3 to generate a new access_token.


Note: Your app will not appear as a Connected App in a user's Integration Settings unless you complete the first two of these steps. You must generate the refresh token and initial access token to have the app appear as "connected."


Query parameters

These parameters are required when building an authorization URL for your app:

 

Required parameters
Required parameter Description How to use
Client ID client_id=x
Used in the URL
Get this from your app's Auth settings page (as described above).
Redirect URL redirect_uri=x
The URL visitors will be redirected to after granting access to your app. 
You'll also designate this on your app's Auth settings page. Note: For security reasons, this URL must use https in production. (When testing using localhost, http can be used.) You also must use a domain, as IP addresses are not supported.
Scope scope=x%20x A space-separated set of permissions that your app needs access to. Any scopes that you've checked off in your app's Auth settings will be treated as required, and you'll need to include them in this parameter or the authorization page will display an error. Additionally, users will get an error if they try to install your app on an account that doesn't have access to an included scope.
See the Scopes table below for more details about which endpoints can be accessed by specific scopes.

 

And here's what's optional:

 

Optional parameters
Optional parameter How to use Description
Optional scopes &optional_scope=x%20x A space-separated set of optional permissions 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 ones were granted. See the table below for more details about scopes.
State &state=y
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_url.
A string value that can be used to maintain the user's state when they're redirected back to your app. 

 

Scopes

OAuth requires you to set scopes, or permissions, for your app. Each scope provides access to a set of HubSpot API endpoints and allows users to grant your app access to specific tools in their HubSpot account. 

Screen Shot 2020-03-26 at 4.21.46 PM

Access to specific APIs or endpoints depends on HubSpot account tier. You can find a full list of available scopes and accessible endpoints in the table below. If your app can work with multiple types of HubSpot accounts, you can use the optional_scope parameter to include any tiered scopes you work. This way, customers using CRM-only accounts can still authorize your app, even if they can't access all of its scopes. Your app must check for and handle any scopes that it doesn't get authorized for.

 

All scopes
 Scope Description Provides access to Required account tier
automation This includes workflows. Automation API (Workflows endpoints) Marketing Hub Professional or Enterprise
business-intelligence This includes endpoints that sit on top of sources and email. Analytics API Any account
contacts This includes contacts and lists. Contact, Companies, Deals, Properties, Engagements, and Owners endpoints Any account
content  This includes sites, landing pages, CTA, email, blog, and campaigns. CMS API and Calendar, Email and Email Events endpoints CMS Hub Professional or Enterprise or Marketing Hub Professional or Enterprise
conversations.visitor_identification.tokens.create  Fetch identification tokens for authenticated website visitors interacting with the HubSpot chat widget. Visitor Identification API Professional or Enterprise
crm.import Allows you to import records into your CRM. This includes creating new records or modifying any of your existing records for all CRM data types (contacts, companies, deals, tickets, etc). It doesn't include archiving or deleting any data. CRM Imports API Any account
e-commerce This includes access to e-commerce features. Products and line items endpoints Sales Hub Professional or Enterprise

Note: Users must be assigned a paid Sales Hub seatto authorize this scope.
files This includes access to File Manager. Files (File Manager) and file mapper (CMS templates, modules, and layout) endpoints Any account
forms This includes access to the Forms endpoints. Forms endpoints

Note: Forms access also requires the contacts scope.
Any account
forms-uploaded-files Download files submitted through a form. Get a file uploaded via form submission endpoint Any account
hubdb This includes access to HubDB. HubDB endpoints CMS Hub Professional or Enterprise or Marketing Hub Professional or Enterprise with Website Add-on
integration-sync This exposes the sync API, which allows syncing of most CRM objects.  Ecommerce Bridge API Any account
oauth Basic scope required for OAuth.   Any account
sales-email-read Grants access to read all details of one-to-one emails sent to contacts. Engagements endpoints

Note: This scope is required to get the content of email engagements. See the Engagements overview for more details.
Sales Hub Free, Starter, Professional, or Enterprise
social This includes Social Inbox. Social Media API Marketing Hub Professional or Enterprise
tickets This includes access to tickets. Tickets endpoints Service Hub Free, Starter, Professional, or Enterprise
timeline Grants access to manage custom events on HubSpot CRM records. This includes creating or updating records. Timeline Events endpoints Any account
transactional-email This includes transactional emails and the transactional emails endpoints. Transactional email endpoints Marketing Hub Professional or Enterprise with Transactional Email Add-on

 


Related docs

Auth methods on HubSpot

OAuth Quickstart Guide

Managing tokens