To initiate an integration with OAuth 2.0:
- First, create an app in a HubSpot developer account. After creating the app, you'll be able to find the app's client ID and client secret on the Auth page of your app settings.
- 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 aredirect_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/
- Any account:
- 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
- Example authorization URLs
- Use the
access_tokento authenticate any API calls made for that HubSpot account. - Once the
access_tokenexpires, use therefresh_tokento generate a newaccess_token.
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. 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.