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 settings.

Connected apps are also able to take advantage of subscribing to changes using webhooks and creating custom timeline events

Create an app

When you create an app in HubSpot, you're essentially associating an app you've built with an app developer account. To get started creating your HubSpot app:

  • In your app developer account, navigate to Apps in the main navigation bar. 
  • In the upper right, click Create app.
  • Next, 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: the app name will be used wherever your app displays in HubSpot. This includes when installing the app as well as the Powered by footer for CRM cards and timeline events.

  • Click the Auth tab to view your client ID and client secret, as well as the app's assigned scopes. You'll need this information when initiating an OAuth connection between your app and HubSpot.

  • On the Auth tab, click the Scopes dropdown menu 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

  • Note the Redirect URL field. 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.

With your app created, you can now walk through the installation process.

Install an app

App installation can be broken down into two steps: authorization and token generation.

Please note: before installing your app, keep in mind the following:

  • 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 in your app developer account and install it there.

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.

Please 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 Grant access 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.

Generate the initial OAuth tokens 

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

Next steps

Once you’ve authorized your app and generated the initial tokens, installation is complete. It’ll be listed on your Connected Apps page, and you’ll start getting webhook and CRM Cards fetch requests.

connected_apps-1


Related resources

Developer tools and accounts

Test accounts

Listing your app