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=$(curl --fail-with-body -sS https://api.anthropic.com/v1/vaults \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF' | jq -r '.id'
{
  "display_name": "Alice",
  "metadata": {"external_user_id": "usr_abc123"}
}
EOF
)
echo "$vault_id"  # "vlt_01ABC..."

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.

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

Passe vault_ids ao criar uma sessão:

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.