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

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

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

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

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

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

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

{
  "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_server_url. Когда агент подключается к серверу MCP во время выполнения сеанса, API сопоставляет URL сервера с активными учетными данными в указанном хранилище и внедряет токен.

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

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

• Одни активные учетные данные на mcp_server_url на хранилище. Создание второго набора учетных данных для того же URL возвращает 409.
• mcp_server_url неизменяем. Чтобы указать на другой сервер, архивируйте эти учетные данные и создайте новые.
• Максимум 20 учетных данных на хранилище. Это соответствует максимальному количеству серверов MCP на агента.

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

Только полезная нагрузка секрета и несколько полей метаданных изменяемы. mcp_server_url, token_endpoint и client_id заблокированы после создания.

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

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

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

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
    title="Alice's Slack digest",
)

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

• Учетные данные переразрешаются периодически во время сеанса, поэтому ротация или архивирование распространяется на работающие сеансы без перезагрузки.
• Когда хранилище не имеет учетных данных для сервера MCP, соединение попытается установиться без аутентификации и выдаст ошибку.
• Когда несколько хранилищ охватывают сервер MCP, первое хранилище с совпадением побеждает.

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

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