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.”
You can also start from the Apps dashboard using the “Create app” button.
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. Please note that the app name will be used wherever your app is displayed for HubSpot users. This includes when installing the app, as well as the "Powered by" footer for CRM cards and timeline events.
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.
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.
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.
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 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.
After choosing an account, you'll be presented with a list of scopes based on the
&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.
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.