---
schema: rendered-html/v1
title: "App Settings | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/app-settings.html
generated_at: 2026-06-11T15:01:57.441031+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- Get Started with Apps
- App Quick Start Guide
- Apps FAQ
- Enhanced DX for TypeScript Apps
- YouTrack App Architecture
- [App Package Overview](jetbrains__com__help__youtrack__devportal__app-overview.md)
- [App Manifest](jetbrains__com__help__youtrack__devportal__app-manifest.md)
- Widgets
- [App Settings](app-settings.html)
- Extension Properties
- [App Permissions](jetbrains__com__help__youtrack__devportal__app-permissions.md)
- Authentication for Apps
- [App Visibility](jetbrains__com__help__youtrack__devportal__app-visibility.md)
- Global and Project Scopes
- Launch Checklist
- App Use Cases
- App Reference
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. Apps
2. Get Started with Apps
3. [App Settings](#0)

# App Settings﻿

Last modified: 07 May 2026

As an app developer, you can add custom settings to your app. System or project administrators in YouTrack can provide values for app settings on the Settings tab of the app on global or project levels respectively.

You can use setting values in custom JavaScript scripts inside the app package, for example, in HTTP handlers, workflow rules, or other scripts. You can refer to a setting value as `ctx.settings.<settingName>`.

For more information about using app settings in the JS code and code samples, see [Using Setting Values in the Scripts](/help/youtrack/devportal/app-settings.html#using-app-values).

## Define App Settings﻿

To define custom app settings, add a file named `settings.json` to the app package. The `settings.json` file must comply to the JSON Schema 2020-12 to be validated on the YouTrack side. For more details about the JSON Schema 2020-12, see [JSON Schema Docs](https://www.learnjsonschema.com/2020-12/).

## Sample Settings File﻿

Here you can find an example of a `settings.json` file of an app.

```
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "title": "App Settings",
    "description": "Here you can provide values for the app settings",
    "properties": {
        "stringSetting": {
            "title": "Name",
            "type": "string",
            "minLength": 1
        },
        "booleanSetting": {
            "type": "boolean"
        },
        "integerSetting": {
            "type": "integer",
            "x-scope": "GLOBAL"
        },
        "numberSetting": {
            "type": "number",
            "x-scope": "PROJECT"
        },
        "secretSetting": {
            "type": "string",
            "format": "secret"
        },
        "arraySetting": {
            "type": "array",
            "items": {
                "x-entity": "User",
                "type": "object"
            }
       },
        "userSetting": {
            "type": "object",
            "x-entity": "User"
            }
    }
}
```

## Supported Setting Types﻿

You can use one of the following entity types for the custom app settings:

- `string`
- `integer`
- `number`
- `boolean`
- `array`
- `object`
- `secret`

## Setting Declaration﻿

A `settings.json` file has the following fields:

| Field | Type | Description | Required |
| --- | --- | --- | --- |
| `type` | string | The type of the entity that is located at the root of the `settings.json` file. The value of this field must always be `object`. | ✓ |
| `title` | string | The title of the file with the setting declaration. This title is displayed on the Settings tab of the app.  You can use this title to give app users more information about the settings that this app allows to configure. |  |
| `description` | string | The description of the file with the setting declaration. It is displayed under the title on the Settings tab of the app.  You can use this description to give app users more details and context about the settings that this app allows to configure. |  |
| `properties` | [object](/help/youtrack/devportal/app-settings.html#properties) | An object that contains definitions of app settings. | ✓ |
| `required` | Array.<string> | An array of properties that represent required app settings. |  |

### Properties﻿

Each app setting must be declared as a field of the `properties` object in the `settings.json` file.

Each key of the `properties` object represents the key name of a setting, while the field value is an object defining the setting.

YouTrack apps support property parameters from the [JSON Schema Draft 07](https://json-schema.org/draft-07/json-schema-validation#rfc.section.6).

Properties are defined with the following parameters:

| Parameter | Type | Description | Required |
| --- | --- | --- | --- |
| `const` | any | The value that the property is restricted to. |  |
| `description` | string | The description of the setting. It will be displayed in the UI as a text label under the setting. |  |
| `enum` | Array.<any> | Defines a closed list of values that the user will be able to choose from. Each element of the list must be unique. |  |
| `exclusiveMaximum` | number | The exclusive upper limit for a numeric value. This parameter is only applicable to settings of the `integer` and `number` types. |  |
| `exclusiveMinimum` | number | The exclusive lower limit for a numeric value. This parameter is only applicable to settings of the `integer` and `number` types. |  |
| `format` | string | The format of the expected value. YouTrack apps support formats from the [JSON Schema Draft 07](https://www.learnjsonschema.com/2020-12/format-annotation/format/).  Here you can find more details about some of the available formats:  | Format | Description | | --- | --- | | `secret` | Use this format for passwords and other input values that should be hidden. | | `date` | A date. A setting with this format displays a calendar for the user to select a date. | |  |
| `items` | object | This parameter must be used for the `array`-typed parameters. The value of this parameter is an object that contains a reference to one of the core YouTrack entities. For more details, see [Arrays](/help/youtrack/devportal/app-settings.html#arrays). |  |
| `maximum` | number | The non-exclusive upper limit for the values that are allowed for this setting. This parameter is only applicable to settings of the `integer` and `number` type. |  |
| `maxLength` | integer | The maximal length of the string that this setting accepts. This parameter is only applicable to settings of the `string` type. |  |
| `minimum` | number | The non-exclusive lower limit for the values that are allowed for this setting. This parameter is only applicable to settings of the `integer` and `number`type. |  |
| `minItems` | integer | The minimal number of items in the array. This parameter is only applicable to settings of the `array` type.  To make an `array`-typed setting required, use this parameter while also listing the setting in the array of [required](/help/youtrack/devportal/app-settings.html#required) settings. |  |
| `minLength` | integer | The minimal length of the string that this setting accepts. This parameter is only applicable to settings of the `string` type. |  |
| `multipleOf` | number | A value is valid only if division by this parameter's value results in an integer. The value must be strictly greater than 0.  This parameter is only applicable to settings of `integer` and `number` types. |  |
| `readOnly` | boolean | When `true`, the value of the setting is read-only and cannot be updated. |  |
| `title` | string | The name of the setting as it will be displayed in the app settings in the YouTrack UI. | ✓ |
| `type` | string | The type of the entity expected as the setting value. The following types are allowed:   - `string` - `integer` - `number` - `boolean` - `array` - `object`   The `array` and `object` types can only represent YouTrack core entities. For details about these types and how to use them in the app settings, see [Using YouTrack Entities for Setting Values](/help/youtrack/devportal/app-settings.html#youtrack-entities-settings). | ✓ |
| `x-entity` | string | This parameter refers to YouTrack core entities that you can use in the app settings. This is a special setting parameter that can only be used for settings of the `array` and `object` types.  For the `array`-typed settings, the value of this parameter represents the type of entities in the array.  For more details, see [Using YouTrack Entities for Setting Values](/help/youtrack/devportal/app-settings.html#youtrack-entities-settings). |  |
| `x-scope` | string | Defines the scope of the setting.  Possible values:  | Scope | Description | | --- | --- | | `GLOBAL` | Settings with this scope can only be configured on the [global level](/help/youtrack/devportal/app-settings.html#set-app-settings-global). | | `PROJECT` | Settings with this scope can only be configured on the [project level](/help/youtrack/devportal/app-settings.html#set-app-settings-project). | |  |

#### Arrays﻿

> ### note
>
> Arrays in YouTrack Scripting APIs
>
> While YouTrack supports arrays in its scripting APIs, including Apps API, Workflow API, and Import API, the functionality of arrays in YouTrack is limited in comparison to the ordinary JavaScript arrays. Namely, in YouTrack, arrays only store unique values without reserved order.
>
> This limitation makes arrays in YouTrack behave similarly to the JavaScript [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) entities.

Each `array`-typed property must be defined with the following parameters:

| Parameter | Type | Description | Required |
| --- | --- | --- | --- |
| `x-entity` | string | This parameter refers to YouTrack core entities that you can use in arrays in the app settings. This is a special setting parameter that can only be used for settings of the `array` and `object` types.  For the `array`-typed settings, the value of this parameter represents the type of entities in the array and should match the value of the corresponding `x-entity` parameter of the `array`-typed property. For more details, see [Using YouTrack Entities for Setting Values](/help/youtrack/devportal/app-settings.html#youtrack-entities-settings). | ✓ |
| `type` | string | Defines the type of the parameter. For the `items` object, this parameter must always be set to `object`. | ✓ |

### Using YouTrack Entities for Setting Values﻿

In app settings with `array` and `object` types, you can use some of the core YouTrack entities for the setting values. The `x-entity` setting parameter defines the exact type of the YouTrack entity that the app expects in a particular setting.

You can use the following YouTrack entities in the app settings:

- `Issue`
- `Article`
- `Project`
- `User`
- `UserGroup`

## Configuring Values for App Settings﻿

When you’re configuring an installed app in YouTrack, you can provide settings for the app on the global or project level. Settings configured on the project level have higher priority and overwrite the global settings. If you don't set any project-level values for app settings, the global-level values for these settings are applied.

### To set values for app settings on the global level:﻿

1. From the Administration menu, select Apps.
2. Select the target app from the list.
3. Open the Settings tab for this app.
4. Update values for the settings of the app.
5. When ready, click the Save button.

   - The values for the app settings are saved on the global level.
   - The values are updated in all projects where this app is attached and where the app settings are synchronized with the global app settings.

### To set values for app settings on the project level:﻿

1. In the project settings, open the Apps tab.
2. Select the target app from the list.
3. Open the Settings tab for this app.
4. Set values for the settings of the app.
5. When ready, click the Save button.

   - The values for the app settings are saved on the project level.
   - The values you've just set overwrite any global-level values for these settings.
   - The settings that you've updated stop being synchronized with the global app settings.

## Working with Settings for Secrets﻿

When you declare a setting that is formatted to store a `secret`, YouTrack handles values stored in the setting differently than it does for other settings. These values are stored securely, ensuring that only authorized parts of the application can access them. This means users can store their authentication tokens and credentials for authorizing the app without having this information fall into the hands of others.

YouTrack handles values stored as secrets in the following manner:

- Once a secret has been stored, no one else can read it anywhere in YouTrack. The real value is used only in the `http.js` package when it is needed to authenticate an HTTP request, namely:

  - bearer token authentication flows. For an example, see [Using Setting Values in the Scripts](/help/youtrack/devportal/app-settings.html#using-app-values) below.
  - basic token authentication.
  - addHeader and setHeader methods. For example, `connection.addHeader('My-Token-Header', ctx.settings.secretToken)`.
  - as the value for a `queryParam` parameter in methods like getSync and others. For example, `connection.getSync(url, { apiKey: ctx.settings.apiKey) }`, the `apiKey` is stored as a secret.
- HTTP requests sent using the `http.js` package are processed inside the JVM, so values stored in secret settings don't appear anywhere in logs.

You can also declare secret settings as required in the `Settings.json` file. When declare as required, the app remains inactivated until these settings are configured, and a corresponding warning is displayed in the App admin UI. This ensures that the app cannot be activated with empty values for secret settings, preventing potential failures in HTTP requests.

## Using Setting Values in the Scripts﻿

You can refer to a setting value as `ctx.settings.<settingName>` in any JavaScript-based script within the app package. For example, you can use setting values in HTTP handlers, workflow rules, import scripts, and other JS scripts.

Here is a code sample for using setting values in an HTTP handler:

```
const entities = require('@jetbrains/youtrack-scripting-api/entities');

  exports.httpHandler = {
      endpoints: [
          {
              method: 'GET',
              path: '/test',
              scope: 'issue',
              handle: function (ctx) {
                  const issue = ctx.issue;
                  issue.description = ctx.settings.stringSetting;
                  if (ctx.settings.booleanSetting) {
                      console.log('integer: ' + ctx.settings.integerSetting);
                      console.log('number: ' + ctx.settings.numberSetting);
                      console.log('array size: ' + ctx.settings.arraySetting.size);
                  }
                  issue.Assignee = ctx.settings.userSetting;
              }
          }
      ],
      requirements: {
          Assignee: {
              type: entities.User.fieldType
          }
      }
  };
```

Here is a code sample for an HTTP handler that uses a setting of the `secret` format:

```
const http = require('@jetbrains/youtrack-scripting-api/http');
const URL = "http://some-third-party-service.io/api";

exports.httpHandler = {
    endpoints: [
        {
            method: 'POST',
            path: '/test',
            handle: function (ctx) {
                let connection = new http.Connection(URL);
                // set 'Authorization: Bearer <token>' header with the secret app setting
                connection.bearerAuth(ctx.settings.secretSetting);
                connection.addHeader('Content-Type', 'application/json');
                let response = connection.postSync("/test", {}, requestJson);
            }
        }
    ]
};
```

- [App Settings](/help/youtrack/devportal/app-settings.html)
- [Define App Settings](/help/youtrack/devportal/app-settings.html#define-app-settings)
- [Sample Settings File](/help/youtrack/devportal/app-settings.html#sample-settings-file)
- [Supported Setting Types](/help/youtrack/devportal/app-settings.html#supported-setting-types)
- [Setting Declaration](/help/youtrack/devportal/app-settings.html#setting-declaration)
- [Properties](/help/youtrack/devportal/app-settings.html#properties)
- [Arrays](/help/youtrack/devportal/app-settings.html#arrays)
- [Using YouTrack Entities for Setting Values](/help/youtrack/devportal/app-settings.html#youtrack-entities-settings)
- [Configuring Values for App Settings](/help/youtrack/devportal/app-settings.html#configuring-values-app-settings)
- [Working with Settings for Secrets](/help/youtrack/devportal/app-settings.html#working-with-secrets)
- [Using Setting Values in the Scripts](/help/youtrack/devportal/app-settings.html#using-app-values)

WidgetsExtension Properties

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
