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

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

Ссылка на хранилище — это параметр уровня сессии, поэтому вы можете управлять своим продуктом на уровне гранулярности ресурса 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 (имя переменной окружения) и хранится в песочнице как непрозрачный заполнитель. Когда агент инициирует исходящий запрос, непрозрачный заполнитель заменяется реальным секретом на выходе. Агент никогда не видит значение секрета. Используйте это для любого сервиса, который аутентифицируется через переменную окружения, например CLI, SDK или прямые вызовы API.

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

CREDENTIAL_ID=$(ant beta:vaults:credentials create \
  --vault-id "$VAULT_ID" \
  --display-name "Alice's Slack" \
  --transform id --raw-output <<'YAML'
auth:
  type: mcp_oauth
  mcp_server_url: https://mcp.slack.com/mcp
  access_token: xoxp-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    token_endpoint: https://slack.com/api/oauth.v2.access
    client_id: "1234567890.0987654321"
    scope: channels:read chat:write
    refresh_token: xoxe-1-...
    token_endpoint_auth:
      type: client_secret_post
      client_secret: abc123...
YAML
)

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

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

• Уникальный ключ в пределах хранилища. 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 объединяются по каждому полю, как описано на вкладке Environment variable в разделе Добавление учётных данных. Для запущенной сессии обновление 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) остаётся видимым и освобождается для заменяющих учётных данных.
• Удаление хранилища или учётных данных: Жёсткое удаление. Запись не сохраняется. Используйте архивацию, если вам нужен журнал аудита.