Autenticar com cofres

Cofres e credenciais são primitivos de autenticação que permitem registrar credenciais para serviços de terceiros uma vez e referenciá-las por ID na criação da sessão. Isso significa que você não precisa executar seu próprio armazenamento de segredos, transmitir tokens em cada chamada ou perder o controle de qual usuário final um agente agiu em nome de.

A referência do cofre é um parâmetro por sessão, portanto você pode gerenciar seu produto no nível do agente e seus usuários no nível da sessão.

Criar um cofre

Um cofre é a coleção de credentials associadas a um usuário final. Dê a ele um display_name e opcionalmente marque-o com metadata para que você possa mapeá-lo de volta para seus próprios registros de usuário.

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

A resposta é o registro completo do cofre:

{
  "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
}

Adicionar uma credencial

Cada credencial se vincula a uma única mcp_server_url. Quando o agente se conecta a um servidor MCP em tempo de execução da sessão, a API corresponde a URL do servidor contra credenciais ativas no cofre referenciado e injeta o token.

Credenciais são armazenadas conforme fornecidas e não são validadas até o tempo de execução da sessão. Um token inválido aparece como um erro de autenticação MCP durante a sessão, que é emitido mas não bloqueia a sessão de continuar.

Restrições:

• Uma credencial ativa por mcp_server_url por cofre. Criar uma segunda credencial para a mesma URL retorna um 409.
• mcp_server_url é imutável. Para apontar para um servidor diferente, arquive esta credencial e crie uma nova.
• Máximo de 20 credenciais por cofre. Isso corresponde à quantidade máxima de servidores MCP por agente.

Rotacionar uma credencial

Apenas o payload secreto e alguns campos de metadados são mutáveis. mcp_server_url, token_endpoint e client_id são bloqueados após a criação.

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

Referenciar o cofre na criação da sessão

Passe vault_ids ao criar uma sessão:

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

Comportamento em tempo de execução:

• Credenciais são re-resolvidas periodicamente durante a sessão, portanto uma rotação ou arquivo se propaga para sessões em execução sem reinicialização.
• Quando um cofre não tem credencial para o servidor MCP, a conexão é tentada sem autenticação e produz um erro.
• Quando vários cofres cobrem o servidor MCP, o primeiro cofre com uma correspondência vence.

Outras operações

• Listar cofres ou credenciais: Paginado, mais recente primeiro. Registros arquivados são excluídos por padrão (passe include_archived=true para incluí-los).
• Arquivar um cofre: POST /v1/vaults/{id}/archive. Cascata para todas as credenciais. Segredos são purgados; registros são retidos para auditoria. Sessões futuras referenciando este cofre falham; sessões em execução continuam.
• Arquivar uma credencial: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Purga o payload secreto; mcp_server_url permanece visível. Libera o mcp_server_url para uma credencial de substituição.
• Deletar um cofre ou credencial: Exclusão permanente. O registro não é retido. Use arquivo se você precisar de uma trilha de auditoria.