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 accounts.

This authentication guide pertains to legacy public apps. For the OAuth guide focused on apps built on the new developer platform, check out this article instead.

Please note:

Any app designed for installation by multiple HubSpot accounts or listing on the HubSpot Marketplace must use OAuth.
Users installing apps in their HubSpot account must either be a Super Admin or have HubSpot Marketplace Access permissions.

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.

Set up OAuth authentication

To set up OAuth authentication for your app:

First, create an app.

Use the client ID and client secret, along with the query parameters and scopes outlined below, to build your authorization URL.
Send users installing your app to the authorization URL, where they’ll be presented with a screen that allows them to select their account and grant access to your integration. You can set the authorization URL to be for a specific HubSpot account by adding the account ID between /oauth/ and /authorize, as shown below. 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 URLs
  - Any account: https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
  - Specific account (ID 123456): https://app.hubspot.com/oauth/123456/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
- Example redirect URL: https://example.com/?code=xxxx
- Example error: https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
Use the access_token to authenticate any API calls made for that HubSpot account.
Once the access_token expires, use the refresh_token to generate a new access_token.

Please note:

Your app will not appear as a Connected App in a user’s account unless you generate the refresh token and initial access token.
Access tokens reflect the scopes requested from the app and do not reflect the permissions or limitations of what a user can do in their HubSpot account. For example, if a user has permissions to view only owned contacts but authorizes a request for the crm.objects.contacts.read scope, the resulting access token can view all contacts in the account and not only those owned by the authorizing user.

Query parameters

The following query parameters are required when building an authorization URL for your app:

Parameter	Description	How to use
`client_id`	An ID that serves as a unique identifier for your app.	Get this from your app’s Auth settings page (as described above).
`redirect_uri`	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`	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 in an account that doesn’t have access to an included scope. Consult the scopes reference documentation for more details about which endpoints can be accessed by specific scopes.

The following parameters are optional:

Parameter	How to use	Description
`optional_scope`	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 doesn’t have access to that tool (e.g., authorizing a Content Hub Enterprise scope in a HubSpot free account). If you’re using optional scopes, you will need to check the access token or refresh token to see which ones were granted. Check out the reference documentation on scopes for more details.
`state`	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`.	A string value that can be used to maintain the user’s state when they’re redirected back to your app.

Configure 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.

Access to specific APIs or endpoints depends on HubSpot account tier. 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 HubSpot free 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. A full list of scopes is available here.

Recommended resources

Set up OAuth authentication

Query parameters

Configure scopes

Auth methods on HubSpot

OAuth Quickstart Guide

Managing tokens

​Recommended resources

​Set up OAuth authentication

​Query parameters

​Configure scopes

​Related docs

Auth methods on HubSpot

OAuth Quickstart Guide

Managing tokens

Recommended resources

Set up OAuth authentication

Query parameters

Configure scopes

Related docs