App configuration - HubSpot docs

Below, find reference information for developer platform app features, including configuration file definitions, scopes details, and more.

Project structure

All project components must live within the src directory specified in the top-level hsproject.json config file.
All app features and components must live within the src/app/ directory. Within this app/ directory, you’ll define subdirectories for each feature you want your app to support:
- App events are configured within app-events/.
- App objects are defined within app-objects/.
- All card features are defined within cards/ .
- Settings page features are defined within settings/.
- Serverless functions are configured within functions/.
- Telemetry is configured within telemetry/.
- Webhook subscriptions are defined within webhooks/.
- Custom workflow actions are defined within workflow-actions/.
Within each feature subdirectory, you’ll configure the feature are using a *-hsmeta.json file. You can prefix the file name with something meaningful to your app (e.g., my-app-hsmeta.json), as long as the file ends with -hsmeta.json. These files must live at the root level of their respective folder (e.g., app/my-app-hsmeta.json, cards/my-card-hsmeta.json).

The example directory structure below outlines all available features. Details for configuring the top-level app schema app-hsmeta.json file are provided in the app schema section below. Once you’re ready to add app features, check out the adding app features section.

my-project-folder/
└── hsproject.json
└── src
    └── app/
        └── app-hsmeta.json/
        └── app-events/
            └── my-event-type-hsmeta.json
        └── app-objects/
            └── my-app-object-hsmeta.json
        └── cards/
            └── MyCard.jsx
            └── my-app-card-hsmeta.json
            └── package.json
        └── functions/
            └── NewFunction.js
            └── private-function-hsmeta.json
            └── package.json    
        └── settings/
            └── Settings.tsx
            └── settings-hsmeta.json
            └── package.json
        └── telemetry/
            └── telemetry-hsmeta.json
        └── webhooks/
            └── webhooks-hsmeta.json
        └── workflow-actions/
            └── custom-action-hsmeta.json

The HubSpot Visual Studio Code extension provides type checking for each of the properties in your *-hsmeta.json configuration files.

Specifying UIDs

The uid field is an internally unique identifier for your specific app, and must also be globally unique within the project. Any app features will each have their own uid defined in their respective *-hsmeta.json files, which must be distinct from the top-level uid you choose in your app’s app-hsmeta.json file.

App schema

The top-level configuration for your app is specified within an app-hsmeta.json configuration file in the app directory.

my-project-folder/
└── src
    └── app/
        └── app-hsmeta.json/

Below are the configuration options available for app-hsmeta.json.

{
  "uid": "new_developer_platform_app",
  "type": "app",
  "config": {
    "description": "An example to demonstrate how to build an app with developer projects.",
    "name": "my first app",
    "logo": "/app/app-logo.png",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

Each of the configuration options are detailed in the table below. More context on distributing your app, configuring authentication, and specifying scopes are provided in the sections below the table.

Fields marked with * are required.

Field	Type	Description
`uid`*	String	An internal unique identifier for the app. Must be globally unique within the project. Can be any string up to 64 characters. Characters can be uppercase or lowercase, and can include numbers, underscores (`_`), dashes (`-`), and periods (`.`).
`type`*	String	The type of component. Must match the name of the parent folder (`app`).
`description`*	String	A description of what the app does for the installing user. Can be any string up to 8192 characters.
`name`*	String	The name of the app, which will display in HubSpot. Can be any string up to 200 characters. Must not start or end with a whitespace character.
`logo`	String	A path to a logo file for your app. Supported file types are: `png`, `jpeg`/`jpg`, `gif`, and `bmp`. Your logo should be recognizable at smaller scales, since it will appear as a thumbnail when the app is installed in HubSpot.
`distribution`*	String	The method of app distribution, which can be set to one of the following: `marketplace`: used if you want the app to be eligible for listing in the HubSpot Marketplace. `private`: used if you only want to install your app in a specific set of allowlisted accounts, or a single account at a time. Learn more in the distribution section below.
`auth`*	Object	An object containing the app’s authentication method details. See the authentication section below for details.
`permittedUrls`	Object	An array containing the URLs that the app is allowed to call. URLs must use the HTTPS scheme and must contain an authority, followed by an optional path prefix if needed.
`supportEmail`	String	A valid email address that users can contact for support.
`documentationUrl`	String	The external URL that users can navigate to for supporting documentation. Must use HTTPS.
`supportUrl`	String	The external URL that users can navigate to for additional support. Must use HTTPS.
`supportPhone`	String	The phone number that users can contact for support. Must start with a plus sign (`+`).

Distribution

The distribution field in your app schema allows you to configure how you want to distribute your app:

If you plan to list your app on the HubSpot Marketplace, set the distribution field to "marketplace". An example app schema for this option can be found here. If you choose this option, ensure that you set the type within the auth property to oauth, as detailed in the authentication section below.
If you want to allow your app to be installed in a specific set of allowlisted accounts, or if you want to restrict installation to a single account at a time, set distribution to "private". Ensure that you set the type within the auth property accordingly:
- If you want to install your app in multiple accounts based on an allowlist you configure in your project settings, set the authentication type to oauth. See the example app schema for this option here.
- To restrict installation to a single account, either the same you use for development or another account that the installing user has access to, set the authentication type to static. An example app schema for static auth can be found here.

Authentication

Authentication for your app is configured via the auth property in your app schema. You can specify your app’s scope requirements, redirect URLs, and authentication type.

Fields marked with * are required.

Field	Type	Description
`type`*	String	The type of authentication, which can be set to one of the following: `oauth`: allow installation via OAuth, either to a specific set of allowlisted accounts or listing it in the HubSpot Marketplace. `static`: restrict installation of your app to a single account that the installing user has access to.
`redirectUrls`*	Array	A list of 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.
`requiredScopes`*	Array	A list of 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. Learn more about scopes below.
`optionalScopes`	Array	A list of 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. Learn more about scopes below.
`conditionallyRequiredScopes`	Array	A list of scopes that are required only when included in the `scope` query parameter of the install URL. Learn more about scopes below.

Scopes

In the auth field of an app configuration file, you can specify three types of scopes: required scopes, conditionally required scopes, and optional scopes. At a minimum, your app must include the read scope to enable customers to access the associated CRM object type (e.g., crm.objects.contacts.read to retrieve contacts).

{
  "uid": "oauth-sample-app",
  "type": "app",
  "config": {
    "description": "An example OAuth app.",
    "name": "my first app",
    "logo": "/app/app-logo.png",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

For a full list of available scopes, see the scopes reference.

Adding app features

To configure app features such as webhook subscriptions, custom workflow actions, and app cards, check out the guides below for details on how to add the associated *-hsmeta.json files to your project:

​Project structure

​Specifying UIDs

​App schema

​Distribution

​Authentication

​Scopes

​Adding app features