There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Authorizing and installing an app

Important! You must generate the refresh token and initial access token before the app will show up as installed in an account.

For a more detailed walkthrough of OAuth and authorization, see our OAuth 2.0 Quickstart Guide.

Before installing an app

  • An app won’t appear on an account’s Connected Apps page until the initial access and refresh tokens are created.
  • Only Super Admins can install apps.
  • Apps can’t be installed on developer accounts. To test your app, you’ll need to create a test account (which is done within your developer account) and install it there.

Getting started

Installing a HubSpot app in an account is a two-step process. First, you'll need to authorize the app for the account that you want to install in. Second, you'll need to generate the initial OAuth tokens using the auth code you get from the first step.

If you haven't created an app to install yet, you can find instructions to do so here.

Authorize your app with an account

The first step in installing your app is to authorize your app with a HubSpot account. To do this, you'll need to create an authorization URL that you'll be sending to users that want to install your app. You'll need the client ID for the app you've created in HubSpot. You can find detailed instructions for building the authorization URL here.

Once you've built your authorization URL, you'll want to direct your users to that URL. It will display a list of accessible HubSpot accounts. (Note that test accounts that you've created from your developer account will list the Sales, Service, and Marketing Enterprise products, as you can see for account 4561 in the image below.) Select the account where you want to install your app.

select_account

After selecting an account, you'll be presented with a list of scopes, based on the &scopes= and &optional_scope= parameters used for the authorization URL.  If you include a scope as an optional_scope, and the selected account doesn't have access to that scope (such as the content scope for a CRM-only account), it will not be listed. Click the “Grant access” button to authorize the connection.

approve_scopes

Once you click Grant access, you'll be redirected based on the &redirect_uri= parameter in the original authorization URL. A ?code= parameter will be appended to the URL. You'll use that code in the next step to generate the access token you'll use to access the HubSpot APIs for the account you selected.

Generate the refresh token and initial access token

After getting the code from the authorization step, you'll need to use that code to generate the refresh token and the initial access token for your app. To do this, you'll need the Client ID and Client Secret, along with the code you got and the redirect_uri you used in your original authorization URL from the first step. You can find detailed instructions for generating the initial tokens here.

After you generate those initial tokens, your app will be considered installed. You'll see the app listed in the installed integrations in the account, and you'll also start getting webhooks and CRM extension fetch requests from the account.

You can view all of the integrations installed in an account by going to Settings > Integrations > Apps.

connected_apps