# Создание и управление секретами

Создайте переиспользуемый типизированный секрет, проверьте его маскированные метаданные и замените или удалите его, не раскрывая сохраненное значение через API секретов.

В этом руководстве создается секрет типа `env` с именем `sandbox-demo` и одной переменной. Выберите другой [тип секрета](/secrets/secret-types.md), если получателю нужен файл, репозиторий или конфигурация учетных данных.

## Перед началом[​](#before-you-begin "Прямая ссылка на Перед началом")

Выберите личный аккаунт или аккаунт организации, которому должен принадлежать секрет. Участник организации может управлять собственными секретами; пользователи с ролью *Владелец* или *Администратор* могут управлять всеми секретами организации.

Для REST-варианта установите cURL и `jq`, используйте персональный токен с правами *Полные* и задайте:

```
export JUSTRUN_API="https://your-just-run-host"
export JUSTRUN_PAT="your-personal-access-token"
```

Секреты зависят от конфигурации шифрования инсталляции. Если хранилище секретов не настроено, эндпоинты возвращают HTTP `503`.

Храните авторитетную копию исходных учетных данных в выпустившей их системе или менеджере паролей. После создания Just Run не предоставляет операцию API, раскрывающую значение секрета.

## Создание через веб-интерфейс[​](#create-through-the-web-ui "Прямая ссылка на Создание через веб-интерфейс")

1. Откройте *Секреты* и нажмите *Новый секрет*.
2. Выберите тип секрета.
3. Введите уникальное имя и необязательное описание.
4. В организации выберите видимость *Личный* или *Организация*.
5. Заполните поля значения для выбранного типа и нажмите *Создать секрет*.

Имя переменной `env` становится переменной окружения в песочнице: латинские буквы, цифры и `_`, первый символ не цифра, не длиннее 128 символов (`DEMO_API_TOKEN`, `_private`). Другое имя форма не сохраняет, а API отклоняет с HTTP `422`.

В списке появятся имя, тип, маскированное значение и пометка *Доступен организации*, если она применима. Исходное значение больше не подставляется в форму.

Секрет также можно создать и сразу выбрать при создании новой песочницы: раскройте *Дополнительные настройки*, затем в разделе *Интеграции* раскройте *Секреты* и нажмите *Создать секрет*.

## Создание через REST API[​](#create-through-the-rest-api "Прямая ссылка на Создание через REST API")

Прочитайте демонстрационный токен, не помещая его в историю командной оболочки, и передайте тело запроса в cURL через конвейер:

```
read -rsp "Demo API token: " DEMO_API_TOKEN
printf '\n'
export DEMO_API_TOKEN

CREATE_RESPONSE="$(
  jq -n '{
    name: "sandbox-demo",
    description: "Environment for the Secrets sandbox walkthrough",
    type: "env",
    value: {
      vars: {
        DEMO_API_TOKEN: env.DEMO_API_TOKEN
      }
    }
  }' |
    curl --fail-with-body --silent --show-error \
      --request POST "$JUSTRUN_API/v1/secrets" \
      --header "Authorization: Bearer $JUSTRUN_PAT" \
      --header "Content-Type: application/json" \
      --data-binary @-
)"

unset DEMO_API_TOKEN
SECRET_ID="$(jq -er '.id' <<<"$CREATE_RESPONSE")"
jq '{id, name, type, visibility, preview}' <<<"$CREATE_RESPONSE"
```

Успешное создание возвращает HTTP `201`. Ответ замаскирован:

```
{
  "id": "42",
  "name": "sandbox-demo",
  "type": "env",
  "visibility": "private",
  "preview": {
    "keys": ["DEMO_API_TOKEN"]
  }
}
```

По умолчанию секрет получает `private` в обоих контекстах аккаунта. В организации можно передать `"visibility": "org"`, чтобы открыть новый секрет всем участникам. В личном аккаунте используется `private`.

Секрет `private` организации можно подключить к личной песочнице или личному серверу Hosted MCP того же автора. Общие получатели отклоняют его. Указывайте `org` только если значение могут использовать все участники.

Имена чувствительны к регистру, уникальны внутри активного аккаунта, содержат от 1 до 64 символов и допускают только буквы ASCII, цифры, `-` и `_`.

## Список и просмотр метаданных[​](#list-and-inspect-metadata "Прямая ссылка на Список и просмотр метаданных")

Ответы со списком отсортированы по имени и содержат маскированные метаданные:

```
curl --fail-with-body --silent --show-error \
  "$JUSTRUN_API/v1/secrets" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq '.[] | {id, name, type, preview, updated_at, last_used_at}'
```

Получите одну запись по строковому ID:

```
curl --fail-with-body --silent --show-error \
  "$JUSTRUN_API/v1/secrets/$SECRET_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq
```

Ни один ответ не содержит `value`, шифртекст или одноразовое число шифрования. Содержимое `preview` — метаданные в открытом виде, доступные всем, кто может просматривать секреты аккаунта.

## Обновление метаданных и ротация значения[​](#update-metadata-or-rotate-the-value "Прямая ссылка на Обновление метаданных и ротация значения")

В веб-интерфейсе нажмите значок карандаша рядом с секретом. Его тип зафиксирован.

Для секрета типа `env` форма показывает имена сохраненных переменных со скрытыми значениями, и сохранение меняет только то, что вы изменили:

* оставьте значение переменной пустым, чтобы сохранить его, или введите новое;
* удалите строку, чтобы удалить переменную;
* нажмите *Добавить переменную*, чтобы добавить новую.

Имя сохраненной переменной не редактируется: чтобы переименовать переменную, удалите ее и добавьте новое имя вместе со значением. Пустое поле сохраняет прежнее значение, поэтому чтобы сохранить пустое значение, удалите переменную и добавьте ее заново без значения.

Для остальных типов поля текущего значения пусты:

* оставьте все поля значения пустыми, чтобы сохранить зашифрованное значение и изменить только имя или описание;
* заполните поля новым значением, чтобы целиком заменить типизированное значение.

REST API также поддерживает обновление только метаданных:

```
curl --fail-with-body --silent --show-error \
  --request PATCH "$JUSTRUN_API/v1/secrets/$SECRET_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{"description":"Rotated by the platform team"}' |
  jq '{id, name, type, description, preview, updated_at}'
```

Для ротации демонстрационного значения передайте тот же тип и полное новое значение:

```
read -rsp "Replacement demo API token: " DEMO_API_TOKEN
printf '\n'
export DEMO_API_TOKEN

jq -n '{
  type: "env",
  value: {
    vars: {
      DEMO_API_TOKEN: env.DEMO_API_TOKEN
    }
  }
}' |
  curl --fail-with-body --silent --show-error \
    --request PATCH "$JUSTRUN_API/v1/secrets/$SECRET_ID" \
    --header "Authorization: Bearer $JUSTRUN_PAT" \
    --header "Content-Type: application/json" \
    --data-binary @- |
  jq '{id, name, type, preview, updated_at}'

unset DEMO_API_TOKEN
```

Замена значения не является объединением. Если при обновлении секрета типа `env` пропустить существующую переменную в `value.vars`, ее не будет в новом сохраненном значении. Не меняйте тип секрета; для другого типа создайте новую запись и переведите получателей на ее имя.

Чтобы изменить отдельные переменные секрета типа `env` и сохранить остальные, передайте `env_vars` вместо `type`/`value`: строка задает переменную, `null` удаляет ее, пропущенные переменные сохраняют значения. Имена подчиняются правилу создания; сохраненную раньше переменную с другим именем можно только удалить. Если параллельная запись изменила значение, API отвечает HTTP `409` `state.conflict`; повторите запрос.

```
curl --fail-with-body --silent --show-error \
  --request PATCH "$JUSTRUN_API/v1/secrets/$SECRET_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{"env_vars":{"OBSOLETE_TOKEN":null}}' |
  jq '{id, name, type, preview, updated_at}'
```

Ответ подтверждает новые маскированные метаданные, а не значение. Для проверки ротации создайте нового получателя с этим секретом: уже материализованные получатели сохраняют предыдущую копию.

## Удаление секрета[​](#delete-the-secret "Прямая ссылка на Удаление секрета")

Нажмите значок корзины в веб-интерфейсе или выполните:

```
curl --fail-with-body --silent --show-error \
  --request DELETE "$JUSTRUN_API/v1/secrets/$SECRET_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT"
```

Удаление возвращает HTTP `204` и идемпотентно. Оно запрещает будущие ссылки по имени, но не стирает значения, уже материализованные в песочницах или развертываниях Hosted MCP. Если существующие копии должны перестать работать, отзовите учетные данные у внешнего провайдера.

## Решение проблем[​](#troubleshooting "Прямая ссылка на Решение проблем")

| Ответ | Значение                                                                                                                                                               |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Неверная спецификация репозитория                                                                                                                                      |
| `403` | Персональный токен с правами *Только чтение* или роль в организации не разрешает запись                                                                                |
| `404` | ID относится к другому аккаунту или не существует                                                                                                                      |
| `409` | `secret.already_exists`: в аккаунте уже есть секрет с таким именем. `state.conflict`: во время обновления `env_vars` значение изменила другая запись; повторите запрос |
| `422` | Неверное имя, видимость, типизированное значение, имя переменной, использование `env_vars`, base64 или размер файла; поле называет `violations[].pointer`              |
| `503` | В инсталляции не настроен ключ шифрования секретов                                                                                                                     |

## Связанные разделы[​](#related "Прямая ссылка на Связанные разделы")

* [Типы секретов и материализация](/secrets/secret-types.md)
* [Область действия и доступ](/secrets/scope-and-access.md)
* [Использование секретов с песочницами](/secrets/use-with-sandboxes.md)
* [Ротация и аудит](/secrets/rotation-and-audit.md)
* [Справочник REST API](/api-reference/rest.md)
