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 a portal.

  • Only super admin users will be able to install an app. You'll see an error if you try to authorize a portal 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 portal, then install the app in that test portal.

Installing a HubSpot app in a portal is a two step process. First, you'll need to authorize the app for the portal 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 a portal

The first step in installing your app is to authorize your app with a HubSpot portal. 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 portal 12345 in the image below.


After selecting a portal, 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 portal doesn't have access to that scope (such as the content scope for a CRM-only portal), it will not be listed. Click the Grant access button to authorize your app to connect to that portal.


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 portal 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 portal, and you'll also start getting webhooks and CRM extension fetch requests from the portal.

You can view all of the integrations installed in a portal by going to the Account Menu > Integrations.