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

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

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



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

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

VAULT_ID=$(ant beta:vaults create --transform id --raw-output < alice.vault.yaml)
echo "$VAULT_ID"  # "vlt_01ABC..."

display_name: Alice
metadata:
  external_user_id: usr_abc123

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

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