Authorizing and installing an app

  • Only administrators will be able to install an app, and you'll see an error if you try to authorize a portal that you're not an administrator in.
  • 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 intial OAuth tokens using the auth code you get from the first step.

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 using the instructions detailed here.

Once you build 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.