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
• Install a public app in an account
• Manage the app, including monitoring usage
• Add a verified domain to the app

​

Create a public app

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

• Navigate to your app developer account:
  • To create a new app developer account, click here, then click Create App Developer account.
  • If you already created an app developer account, navigate to the account selection page, then locate and click your account.
• In your app developer account, navigate to Apps in the main navigation bar.
• In the upper right, click Create app.
• Next, enter your App name, and provide other basic information about your app, including a description and logo. 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.

• Click the Auth tab.

• Enter a Redirect URL for your app. Users will be redirected to this URL after granting access and the associated account permissions to your app. If you’re just getting started and you don’t have an official redirect URL ready yet, you can also use http://localhost for local development as you build out and test your app.

Next, you’ll configure the scopes your app will require.

​

Configure scopes

Scopes determine your app’s permissions to access data sources or tools in an account that’s installed your app. The scopes you configure will appear as the scope and optional_scope query parameters in an install URL that you can then provide to users.

​

Scope types

On the Auth tab, there are three different scope types available for you to configure. You must specify the scopes your app will require for installation, but you can also specify two other scope types: conditionally required scopes and optional scopes.

• Required scopes: scopes that must be authorized by the user and must be present in the scope query parameter in your app’s install URL for successful installation.
• Conditionally required scopes: scopes that must be authorized by the user only if they’re present in the scope query parameter in your app’s install URL for successful installation.
  • This scope type allows you to be flexible and provide a separate install URL for tiered features or scopes that are only required when users enable certain features in your app. For example, you could offer two install URLs to your users: one install URL could include the conditionally required scope in the scope query parameter for users with access to a feature, while another install URL omits that scope in the scope query parameter for users without access.
  • If a conditionally required scope is present in your app install URL and a user without access to the associated feature attempts to install your app using that URL, the installation will fail.
• Optional scopes: scopes that are not required to successfully install your app. These scopes are specified in the optional_scope query parameter in your app’s install URL. For example, if you want your app to be able to fetch custom object data (which is only available to Enterprise HubSpot accounts), you could add the crm.objects.custom.read scope as an optional scope. Then, if an account has access to the custom objects, the scope will be authorized. Otherwise, they’ll still be able to install the app without the custom objects scope.

​

Add scopes

To customize your scope settings and add new scopes:

• In the Scopes section, click Add new scope.
• In the right panel, use the search bar to search for a scope, then select the checkbox next to any scope you want the user to authorize. Click the dropdown menu next to the scope and select a scope type.
• Click Update.

• Review your configured scopes. If you turned on advanced scope settings, you can switch the scope type of any scope by clicking the dropdown menu next to the scope. You can also click Delete to remove one of your app’s scopes.

• Once you’ve finished setting up your app settings, click Create app in the bottom left.

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

​

Install an app

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.

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

• Click Grant access 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.

​

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.

​

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.

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

​

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.

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.

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

On each tab, if any associated events occurred in the last 30 days (e.g., a webhook trigger occurred or an API call was made), you can click Export logs to export the associated event data to a CSV:

• In the dialog box, configure how many days’ worth of data to export (up to 30 days).
• Click Export. An email notification will be sent to the email address associated with your user in your HubSpot settings.

​

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.

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

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

​

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.

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

• In your DNS provider, create a TXT record with the copied value. Below are instructions for some common DNS providers:
  • GoDaddy
  • BlueHost
  • Namecheap
  • Cloudflare
  • Hover
  • Name
  • United Domains
• 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.

​

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.