> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: a2497c50-331b-40c6-9557-dba51045521a
---

# App configuration

> Reference information for configuration options for apps built on the new developer platform

<style>
  {`
    .github-link a div,
    .github-link a div p {
      display: inline;
      margin: 0;
      padding: 0;
    }
    .github-link {
      background-color: rgb(255, 255, 255);
      border-radius: 24px;
      box-shadow: rgba(0, 0, 0, 0.25) 0px 2px 4px 0px;
      padding: 5px;
      max-width: 247px;
      display: flex;
      align-items: center;
      margin-bottom: 20px;
    }
    .github-icon {
        display: inline;
        width: 24px;
        margin-right: 8px;
        flex-shrink: 0;
    }
    .table-key, .table-key div, .table-key p {
      margin: 0;
      font-size: 14px;
    }
    `}
</style>

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](#app-schema) below. Once you're ready to add app features, check out the [adding app features](#adding-app-features) section.

```shell theme={null}
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](/developer-tooling/local-development/vs-code-extension#validate-hs-meta-json-config-files) 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](#adding-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.

```shell theme={null}
my-project-folder/
└── src
    └── app/
        └── app-hsmeta.json/
```

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

```json theme={null}
{
  "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](#distribution), configuring [authentication](#authentication), and specifying [scopes](#scopes) are provided in the sections below the table.

<p className="table-key">
  Fields marked with <span style={{ color: 'red' }}>\*</span> are required.
</p>

| Field                                               | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uid`<span style={{color:"red"}}>\*</span>          | 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`<span style={{color:"red"}}>\*</span>         | String | The type of component. Must match the name of the parent folder (`app`).                                                                                                                                                                                                                                                                                                                               |
| `description`<span style={{color:"red"}}>\*</span>  | String | A description of what the app does for the installing user. Can be any string up to 8192 characters.                                                                                                                                                                                                                                                                                                   |
| `name`<span style={{color:"red"}}>\*</span>         | 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`. <br /> <br /> Your logo should be recognizable at smaller scales, since it will appear as a thumbnail when the app is installed in HubSpot.                                                                                                                                                       |
| `distribution`<span style={{color:"red"}}>\*</span> | String | The method of app distribution, which can be set to one of the following:<ul><li>`marketplace`: used if you want the app to be eligible for listing in the HubSpot Marketplace.</li><li>`private`: used if you only want to install your app in a specific set of allowlisted accounts, or a single account at a time.</li></ul> <p>Learn more in the [distribution](#distribution) section below.</p> |
| `auth`<span style={{color:"red"}}>\*</span>         | Object | An object containing the app's authentication method details. See the [authentication section](#authentication) 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](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL#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](https://ecosystem.hubspot.com/marketplace/apps), set the `distribution` field to `"marketplace"`. An example app schema for this option can be found [here](https://github.com/robrown-hubspot/hubspot-project-components-ua-app-objects-beta/blob/main/projects/public-app-getting-started-template/src/app/app-hsmeta.json). If you choose this option, ensure that you set the `type` within the `auth` property to `oauth`, as detailed in the [authentication](#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](/apps/developer-platform/build-apps/manage-apps-in-hubspot#manage-authentication-for-your-app), set the authentication `type` to `oauth`. See the example app schema for this option [here](https://github.com/robrown-hubspot/hubspot-project-components-ua-app-objects-beta/blob/main/projects/private-app-oauth-getting-started-template/src/app/app-hsmeta.json).
  * 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](https://github.com/robrown-hubspot/hubspot-project-components-ua-app-objects-beta/blob/main/projects/private-app-static-getting-started-template/src/app/app-hsmeta.json).

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

<p className="table-key">
  Fields marked with <span style={{ color: 'red' }}>\*</span> are required.
</p>

| Field                                                 | Type   | Description                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`<span style={{color:"red"}}>\*</span>           | String | The type of authentication, which can be set to one of the following: <ul><li>`oauth`: allow installation via OAuth, either to a specific set of allowlisted accounts or listing it in the HubSpot Marketplace.</li><li>`static`: restrict installation of your app to a single account that the installing user has access to. </li></ul> |
| `redirectUrls`<span style={{color:"red"}}>\*</span>   | 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`<span style={{color:"red"}}>\*</span> | 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](#scopes).                                                                                                                                 |
| `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](#scopes).        |
| `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).                                                                                                                                                                                         |

### Scopes

In the `auth` field of an app configuration file, you can specify three [types of scopes](/apps/developer-platform/build-apps/authentication/scopes#app-scope-types): 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).

```json highlight={12-14} theme={null}
{
  "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](/apps/developer-platform/build-apps/authentication/scopes).

## 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:

* [Create an app card](/apps/developer-platform/add-features/ui-extensions/extension-points/app-cards/create-an-app-card)
* [Create serverless functions](/apps/developer-platform/add-features/serverless-functions/overview)
* [Define app events](/apps/developer-platform/add-features/app-events/overview)
* [Create app objects](/apps/developer-platform/add-features/app-objects/quickstart-guide-to-app-objects)
* [Create a settings component](/apps/developer-platform/add-features/ui-extensions/extension-points/create-a-settings-page)
* [Set up a custom workflow action](/apps/developer-platform/add-features/custom-workflow-actions)
* [Configure a webhook subscription](/apps/developer-platform/add-features/configure-webhooks)
* [Add telemetry](/apps/developer-platform/add-features/add-telemetry)