Public apps

In HubSpot, a public 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

Below, learn how to:

Create a public 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 connectionbetween 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.

Please note: it's recommended to add a verified domain to the app to add another level of trust for users installing your app. Otherwise, the app will display a banner stating that the app is not verified.

Install an app

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.

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

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 &scope= 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

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

 

Manage public apps in HubSpot

Find an app's ID

You can find a public app's ID in your app developer account using either of the methods below:

  • In your developer account, navigate to Apps in the main navigation bar, then view the App ID listed below the name of your app.
find-app-id
  • In your developer account, navigate to Apps in the main navigation bar, then click the name of the app. On the Basic info page, click the Auth tab, then view the App ID.

find-app-id-auth-settings

Monitor app behavior

HubSpot logs all requests made to or from a connected app, including incoming requests using an OAuth access token or outgoing requests for webhooks or CRM cards. 

To view this request log:

  • In your developer account, navigate to Apps in the main navigation bar.
  • Click the name of the app.
  • In the left sidebar menu, navigate to Monitoring
  • Use the tabs to view different types of requests being made to or from the app. While viewing these logs, you can click an individual request to view more information about it, including:
    • for successful requests, the request method, path, and time of request.
    • for unsuccessful requests, additional error information such as response headers and body.

request_details

Below, learn more about each tab of the Monitoring page.

  • API calls: the API calls tab shows all requests made to your app using an OAuth access token. It can be filtered by HTTP method, response code, timeframe, or request URL.
  • Webhooks: the Webhooks tab shows HubSpot requests for any of your app’s webhook subscriptions. Filter by response (including timeouts and connection failures), status (success, will retry, or failure), subscription type, time frame, attempt, batch, event, or account ID. 

Please note: the attempt ID is a combination of the subscriptionId, eventId, and attemptNumber from a specific request.

  • CRM extensions: the CRM extensions tab shows requests for your app’s CRM cards. Filter by extension object type, CRM object type (contact, company, ticket, or deal), error or warning type, time frame, request ID, or CRM record ID (i.e. a specific contact ID).
  • App settings: the App settings tab enables you to configure the settings page that comes with your app. 

Add a verified domain

When HubSpot users install an app, they consent to give the app’s developer access to their account data. The developer’s identity and reputation each play an important role in a user’s decision to continue with the install. To ensure full user consent when installing an app, HubSpot will display a message on the app install screen to indicate the app's level of verification and App Marketplace listing:

  • When an app doesn't have a verified domain, HubSpot will display a banner on the install screen that says the app has not been verified.
    not-verified
  • When app has a verified domain but is not listed on the App Marketplace, HubSpot will display the verified domain along with a banner on the install screen that says the app has not been reviewed or approved by HubSpot. verified-not-listed
  • When an app has been listed on the marketplace, passing HubSpot's app review process, HubSpot will not display either of the above banners. You're not required to verify the domain if your app has been listed on the App Marketplace.
    verified-and-listed

Add a verified domain

To add a verified domain to the app, you'll need to first add the domain to the app's settings, then add a TXT record to the domain's DNS settings:

  • In your app developer account, navigate to Apps.
  • Click the name of the app.
  • In the left sidebar, navigate to Contact & support.
  • In the Company domain field, enter your domain, then click Save. A message will appear below the Company domain stating that the domain has not yet been verified.
  • Click Verify it now to begin the verification process.

domain-verification-for-app


  • In the right panel, confirm that the domain has been entered correctly, then click Next.
  • Copy the required TXT record value by clicking Copy in the Value column.
    verify-app-domain-copy-value
  • In your DNS provider, create a TXT record with the copied value. Below are instructions for some common DNS providers:
  • After updating your DNS settings, navigate back to HubSpot, then click Next in the right panel. DNS records can take up to 48 hours to update, so HubSpot might not recognize the change immediately. You can get back to this screen any time by selecting Verify it now again from the Company info settings page.
  • Once verified, you'll see a success status indicator under the Company domain field.

Domain verified__export

Additional Notes

  • To ensure continued ownership of the domain, HubSpot will continue to verify that the TXT record is present on a regular basis. The install warning will return if the TXT record is removed or modified.
  • Currently, you can only have one verified domain per developer account. All apps in an account share the verified domain. The domain on the install page will link to your root domain.
  • If you delete your verified domain, all apps in your developer account will get the install warning again. You can verify another domain, but the process will take a couple hours.