Creating and installing apps

In HubSpot, an app is a type of integration that can be installed on customer accounts or listed on the App Marketplace. It requires authentication via OAuth. Once a user installs your app on their HubSpot account, you’ll be able to make API calls to that account using an OAuth access token. Your app will also appear in the account’s Connected Apps page (Settings > Integrations > Connected Apps), where users can manage or uninstall it.

Certain integration features are only available through apps—they can't be used with 1:1 integrations. For example, only installed apps can subscribe to changes using webhooks or create custom timeline events and CRM cards. While not required, an app is also strongly recommended for the Ecommerce Bridge.

Creating an app

When you create an app in HubSpot, you're essentially associating an app you've built with a developer account. Once you’re set up and signed in, you'll start on the developer account homepage, where you'll have the option to create your first app or create a test account. Click “Create an app.”

 

dev_landing_dash

You can also start from the Apps dashboard using the “Create app” button.

app_dash_first_app

1. Basic info

Next, you’ll fill out some basic information and settings for your app. When users authenticate your app with their HubSpot account, they’ll see the name, description, logo, and any support contact info you provide on this page. 

2. Auth settings

In the next tab, you’ll find your Auth settings, including the client ID and client secret. This is also where you’ll set up scopes for your app. You’ll need this information for initiating an OAuth connection between your app and HubSpot.

3. Scopes

Click on the dropdown at the bottom of the page to add new scopes to your app. These required scopes must be included in the scope= parameter of your authorization URL or users will get an error when trying to authorize your app. See the OAuth docs for more information about building your authorization URL and using scopes.

app_scopes

4. Redirect URL

This is where users will be sent after granting your app access to their HubSpot account. If you don't include a redirect URL, users will get a connection error. Redirect URLs must use HTTPS, unless they're on localhost.


Installing apps

Before installing an app

Important notes: 
  • An app won’t appear on an account’s Connected Apps page until the initial access and refresh tokens are created.
  • Only users with with access to an app’s required scopes can install an app.
  • 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.

How to install an app

Installing an app can be broken down into two steps: authorization and token generation. 

1. Authorize your app with a customer account 

To authorize your app with a HubSpot account, you’ll need to create an authorization URL. Do this by getting the client ID for your app and initiating the OAuth process.

Once your URL is ready, open it in your browser to see a list of all your HubSpot accounts. (This is also what users will see once you begin directing them to this URL.) Select the account where you want to install your app.

select_account-1

After choosing an account, you'll be presented with a list of scopes based on the &scopes= and &optional_scope= parameters you set for the authorization URL. Note: If you include an optional_scope and the selected account doesn't have access to it (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-1

After granting access, you'll be redirected based on the &redirect_uri= parameter in the original authorization URL and a ?code= parameter will be appended to the URL. Use that code in the next step to generate an access token.

2. Generate the initial OAuth tokens using the auth code provided during authorization

To generate your refresh and initial access tokens, you’ll need the code from the ?code= parameter of the authorization URL, redirect_url from Step 1, client ID, and client secret. Detailed instructions are here

 

After installing an app

Once you’ve authorized your app and generated the initial tokens, installation is complete. It’ll be listed on your Connected Apps page (which can be found under Settings > Integrations > Connected Apps), and you’ll start getting webhook and CRM Cards fetch requests.

connected_apps-1


Related docs

Developer tools and accounts

Test accounts

Listing your app