Аутентификация с помощью хранилищ

Хранилища (vaults) и учётные данные (credentials) — это примитивы аутентификации, которые позволяют один раз зарегистрировать учётные данные для сторонних сервисов и затем ссылаться на них по идентификатору при создании сессии. Это означает, что вам не нужно поддерживать собственное хранилище секретов, передавать токены при каждом вызове или терять контроль над тем, от имени какого конечного пользователя действовал агент.

Ссылка на хранилище — это параметр уровня сессии, поэтому вы можете управлять своим продуктом на уровне ресурса agent, а пользователями — на уровне ресурса session.



Создание хранилища

Хранилище — это набор credentials, связанных с конечным пользователем. Задайте ему display_name и при необходимости пометьте его с помощью metadata, чтобы можно было сопоставить его с вашими собственными записями о пользователях.

VAULT_ID=$(ant beta:vaults create \
  --display-name "Alice" \
  --metadata '{external_user_id: usr_abc123}' \
  --transform id --raw-output)
echo "$VAULT_ID"  # "vlt_01ABC..."

В ответе возвращается полная запись хранилища:

{
  "type": "vault",
  "id": "vlt_01ABC...",
  "display_name": "Alice",
  "metadata": { "external_user_id": "usr_abc123" },
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z",
  "archived_at": null
}



Добавление учётных данных

Поддерживаются две категории учётных данных:

• Учётные данные MCP (mcp_oauth, static_bearer): каждая запись учётных данных идентифицируется по mcp_server_url. Когда агент подключается к серверу по этому URL во время выполнения сессии, токен подставляется автоматически.
• Переменные окружения (environment_variable): каждая запись учётных данных идентифицируется по secret_name (имя переменной окружения) и хранится в песочнице как непрозрачный заполнитель. Когда агент инициирует исходящий запрос, непрозрачный заполнитель заменяется реальным секретом на выходе (egress). Агент никогда не видит значение секрета. Используйте этот тип для любого сервиса, который аутентифицируется через переменную окружения, например CLI, SDK или прямые вызовы API.

Фактические значения учётных данных, которые вы передаёте (token, access_token, refresh_token, client_secret, secret_value), рассматриваются как конфиденциальные поля, доступные только для записи, и никогда не возвращаются в ответах API.

Учётные данные сохраняются в том виде, в каком были переданы, и не проверяются до момента выполнения сессии. Недействительные учётные данные проявляются как ошибка аутентификации или ошибка нижестоящего сервиса во время сессии; такая ошибка генерируется, но не блокирует продолжение сессии.

Ограничения:

• Уникальный ключ в пределах хранилища. mcp_server_url (учётные данные MCP) и secret_name (учётные данные типа переменных окружения) должны быть уникальными среди активных учётных данных в хранилище. Создание дубликата возвращает ошибку 409.
• Ключи неизменяемы. Чтобы изменить mcp_server_url или secret_name, заархивируйте учётные данные и создайте новые.
• Максимум 20 записей учётных данных на хранилище.



Ссылка на хранилище при создании сессии

Передайте vault_ids при создании сессии:

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --vault-id "$VAULT_ID" \
  --title "Alice's Slack digest" \
  --transform id --raw-output)

Поведение во время выполнения:

• Если ни одни учётные данные MCP не совпадают по mcp_server_url, подключение выполняется без аутентификации и завершится ошибкой, если сервер требует аутентификацию.
• Если несколько хранилищ содержат совпадающие учётные данные, приоритет имеет первое хранилище с совпадением.
• В многоагентных сессиях учётные данные хранилища применяются к каждому потоку. Агент, в собственном определении которого объявлен соответствующий сервер MCP, аутентифицируется с этими учётными данными. См. Подключение агентов к серверам MCP.



Ротация учётных данных

Значения секретов, display_name и (для учётных данных типа переменных окружения) injection_location можно обновлять. Обновления injection_location объединяются по отдельным полям, как описано на вкладке «Переменная окружения» раздела Добавление учётных данных. Для выполняющейся сессии обновление injection_location распространяется так же, как и ротация секрета: учётные данные сессии повторно разрешаются без перезапуска, как описано в разделе Жизненный цикл учётных данных, и обновлённые расположения применяются к последующим исходящим запросам сессии. Структурные поля (mcp_server_url, secret_name, token_endpoint, client_id) фиксируются после создания. Чтобы изменить их, заархивируйте учётные данные и создайте новые.

ant beta:vaults:credentials update \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" <<'YAML'
auth:
  type: mcp_oauth
  access_token: xoxp-new-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    refresh_token: xoxe-1-new-...
YAML



Жизненный цикл учётных данных

Учётные данные периодически повторно разрешаются — как во время сессии, так и в течение жизненного цикла хранилища. Это гарантирует, что ротация, архивирование или удаление учётных данных распространяются на выполняющиеся сессии без перезапуска.

Чтобы получать уведомления об архивировании, удалении или сбое обновления учётных данных, вы можете подписаться на вебхуки хранилищ и учётных данных, связанные с этими изменениями жизненного цикла.

Для учётных данных mcp_oauth повторное разрешение также обновляет токен доступа, если срок его действия истёк. Если обновление завершается неудачей, генерируется событие vault_credential.refresh_failed.



Диагностика сбоя обновления OAuth

Чтобы диагностировать причину сбоя обновления, вызовите POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate (или client.beta.vaults.credentials.mcp_oauth_validate(...) в SDK). Это позволит вам решить, как обработать сбой; правильное действие зависит от типа ошибки.

Поле верхнего уровня status указывает, что делать дальше:

• valid: токен работает; никаких действий не требуется.
• invalid: грант отозван или сервер OAuth отклонил обновление с ошибкой 4xx. Предложите конечному пользователю повторно авторизоваться.
• unknown: временная ошибка (5xx, 429 или сетевой сбой). Подождите и повторите попытку.

ant beta:vaults:credentials mcp-oauth-validate \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" \
  --transform status --raw-output  # "valid", "invalid", or "unknown"

Ответ представляет собой объект vault_credential_validation. Поле mcp_probe содержит шаг рукопожатия MCP, на котором произошёл сбой; поле refresh содержит результат попытки обновления.

{
  "type": "vault_credential_validation",
  "credential_id": "vcrd_01ABC...",
  "vault_id": "vlt_01XYZ...",
  "validated_at": "2026-04-29T17:12:00Z",
  "has_refresh_token": false,
  "status": "invalid",
  "mcp_probe": {
    "method": "initialize",
    "http_response": {
      "status_code": 401,
      "content_type": "application/json",
      "body": "{\"error\":\"invalid_token\"}",
      "body_truncated": false
    }
  },
  "refresh": {
    "status": "no_refresh_token",
    "http_response": null
  }
}



Другие операции

• Получение списка хранилищ или учётных данных: с пагинацией, сначала новые. Заархивированные записи по умолчанию исключаются (передайте include_archived=true, чтобы включить их).
• Архивирование хранилища: POST /v1/vaults/{id}/archive. Каскадно применяется ко всем учётным данным. Секреты удаляются; записи сохраняются для аудита. Будущие сессии, ссылающиеся на это хранилище, завершаются ошибкой; выполняющиеся сессии продолжают работу.
• Архивирование учётных данных: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Удаляет содержимое секрета; ключ учётных данных (mcp_server_url или secret_name) остаётся видимым и освобождается для замещающих учётных данных.
• Удаление хранилища или учётных данных: полное удаление. Запись не сохраняется. Используйте архивирование, если вам нужен журнал аудита.