Skip to main content

Public apps enable you to authenticate requests to HubSpot's APIs in your project using OAuth. Public apps can be installed in multiple accounts through a streamlined end-user flow, and can be submitted to HubSpot's App Marketplace. When creating using the developer projects framework, public apps can include UI extensions in addition to other app extensions, such as timeline extensions and workflow actions.

Below, learn how to create and configure a public app using projects.

Before getting started, ensure you've also set up the following:

Using the CLI, you can create a project with a public app using any of the following methods:

  • Follow the quickstart guide to create an app from a boilerplate project template, which includes a card for contact records.
  • Migrate an existing public app to the developer projects framework.
  • Create a public app from scratch locally with a developer project.

To create a public app from scratch:

  • In the terminal, navigate to the directory that you'll be storing your project files in.
  • Since you'll need to deploy your project to your app developer account, set it as the default account by running hs accounts use <accountName> and selecting your developer account.
  • Run hs project create to create a new project.
  • Follow the prompts in the terminal to enter a name and location for the project.
  • When prompted to choose a template, select Create an empty project (no template).
  • With your project created, navigate into the newly created directory using the cd command.
  • Create the following files and directories:
    • In the src directory, create an app directory.
    • In src/app, create a public-app.json file. Below is the minimum schema required for uploading an app. View the full public-app.json schema in the App configuration section below.
  • After saving the file, upload it to your developer account by running hs project upload. Then, follow the prompts in the terminal to create the project in your account.

Public apps built with projects include a public-app.json file to configure the app's details, such as its name, scopes, included extension files, and more.

The public-app.json file uses the following schema:

ParameterTypeDescription
nameStringThe app's name. Can be any string up to 200 characters. Must not start or end with a whitespace character.
uidStringThe app's unique ID. Can be any string up to 64 characters. Characters can be uppercase or lowercase, and can include numbers, underscores (_), dashes (-), and periods (.).
descriptionStringDescribes what the app does for the installing user. Can be any string up to 8192 characters.
logoStringThe file path for the app's logo, which appears next to the app's name. Must be a valid image with one of the following extensions:
  • png
  • jpeg/jpg
  • gif
  • bmp
The image must be less than 5,000,000 bytes (roughly 5MB).
allowedUrlsArrayAn array containing the URLs that the React app is allowed to call. URLs must use the HTTPS scheme and must contain an authority, followed by an optional path prefix if needed. You do not need to add any override URLs specified in local.json to this array.A request URL will match an allowed URL match when:
  • The scheme is HTTPS
  • The authority is an exact match
  • The path starts with the allowed URL's path prefix if specified.
Query parameters are ignored. Regex is not supported.In the above example code, the following request URLs will be allowed:And the following request URLs will not be allowed:The local development server will log a warning if the UI extension requests a URL that doesn't match any of the allowedUrls, but will allow the request through.
redirectUrlsArrayAn array of strings containing the URLs that the OAuth process is allowed to reroute back to. Each app must have at least one auth redirect URL, and it must use HTTPS. The only exception is that http://localhost is allowed for testing.
advancedScopeSettingsEnabledBooleanConfigures when optional and conditionally required scopes can be added to your app's auth configuration. When set to false, new scopes for conditionally required or optional scopes cannot be added or enforced (default is true).Please note: you must set this field to true (or leave unspecified) and declare your app's use of optional and conditionally required scopes when seeking update approval for your App Marketplace app after adding a UI extension.
requiredScopesArrayAn array of strings listing your app's required scopes. Each app must include at least one scope, and the installing user must grant these scopes to successfully install the app. See full list of scopes.
optionalScopesArrayAn array of strings listing your app's optional scopes. These scopes can be excluded from the authorization during installation if the account or user installing the app doesn't have the proper permissions. In that case, the scope will not be included in the resulting refresh token or access token. See full list of scopes.
supportEmailStringA valid email address that users can contact for support.
documentationUrlStringThe external URL that users can navigate to for supporting documentation. Must use HTTPS.
supportUrlStringThe external URL that users can navigate to for additional support. Must use HTTPS.
supportPhoneStringThe phone number that users can contact for support. Must start with a plus sign (+).
extensionsObjectAn object that defines the path to the relevant UI extension configuration file for each app card. Multiple extensions can be included as comma-separated file objects in the cards array.
webhooksObjectAn object that defines the path to the app's webhooks configuration file.

When building public apps using projects, some features must be updated locally in your project files, while others must be managed in the app settings UI in HubSpot.

The following app details can only be managed in your local project files:

All other public app features, such as timeline events, will need to be maintained using the in-app app settings page in HubSpot. When a setting can only be managed locally, the app settings page will disable the field and display a lock icon, which you can hover over for more information.

app-settings-fields-ui-for-project-based-apps

To view and manage your app in HubSpot, including monitoring usage:

  • In the left sidebar of your developer account, navigate to Apps.

developer-account-apps-nav

  • Click the name of the app.

  • On the App Info tab, you can view basic information about your app, such as the app name and description. Fields that are greyed out with a lock icon can only be updated locally.

    public-app-settings-page

  • Click the Auth tab to view the app's authentication information, such as App ID, Client ID, Client secret, Install URL, and scopes.

  • In the left sidebar, navigate to Contact & Support to view the app's company information and support details. On this tab, you can also set up a verified domain.

  • In the left sidebar, navigate to Monitoring to monitor your app's usage data. For public apps built with projects, you can also view detailed UI extension logs.

  • In the left sidebar, you can also view the app's features, including:

On the Monitoring page, you can view logs for the app's UI extensions, including logs for extension rendering and hubspot.fetch() requests. To view an app's UI extension logs:

  • In the left sidebar of your developer account, navigate to Apps.

    developer-account-apps-nav

  • Click the name of the app.

  • On the app settings page, in the left sidebar, click Monitoring.

public-app-monitoring

  • Click the UI extensions tab.

    public-app-monitoring-ui-extensions

  • In the table, you can view all logs for the app's included UI extensions. To filter logs by specific criteria, use the Filter by dropdown menus:

    • Result: filter logs by the type of result, including error and success logs for extension rendering and hubspot.fetch() requests.
    • CRM object type: filter logs by the type of CRM object associated with the event.
    • Extension name: filter logs by extension, which can be useful when your app includes multiple extensions.
  • To view more details for an event, click the event, then view the right panel.

    • You can use the Log ID or Request ID to search for the event by ID on the UI extensions tab.

      public-app-monitoring-ui-extensions-request-id

    • You can use the Trace ID or Traceparent value to search for the event on the Log traces tab. Alternatively, you can click View log trace to navigate directly to the event on the Log traces tab.

      public-app-monitoring-ui-extensions-log-traces

Learn more about log traces below.

When troubleshooting errors, log traces are helpful for quickly debugging issues. You can navigate to log traces directly from an event on the UI extensions tab by clicking View log trace, or by searching for the event by trace ID on the Log traces tab.

public-app-monitoring-ui-extensions-log-traces-tab

When viewing the log trace for an event, you'll see a more detailed breakdown of the event, including error details, request timing, and more, in the Log details section.

public-app-monitoring-ui-extensions-log-tracing-example-2

To delete a public app that was created in a project, you'll first need to delete the project and its association to the app.

To delete a project associated with a public app:

  • In the left sidebar of your developer account, navigate to Projects.

    developer-account-left-sidebar-navigation

  • Click the name of the project.

  • Click the Settings tab, then click Delete [project name].

    developer-account-delete-project

  • In the dialog box, enter the project name and click Delete project.

With the project deleted, you can delete the app:

  • In the left sidebar of your developer account, click Apps.

  • Click the name of the app.

  • On the App info tab, in the Delete this app section, click Delete [app name].

    delete-this-public-app

  • In the dialog box, click the Export your logs link to export a record of the app's activity. Then, select the I've exported the logs checkbox and click Delete.