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.

  • Only super admin users will be able to install an app. You'll see an error if you try to authorize an account when you're not a super admin.
  • Apps cannot be installed into developer portals. If you want to test an app, you'll need to create a test account, then install the app in that test account.

Installing a HubSpot app in a 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 for creating an app in HubSpot 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 built your authorization URL, you'll want to direct your users to that URL, where they'll be presented with a list of HubSpot portals that they have access to. Note that test portals that you've created from your developer account will show a type of Trial, as you can see for account 12345 in the image below.


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 your app to connect to that account.


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 a account by going to Settings > Integrations > Apps.