Autenticar com vaults

Vaults e credenciais são primitivas de autenticação que permitem registrar credenciais para serviços de terceiros uma única 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 em nome de qual usuário final um agente atuou.

A referência ao vault é um parâmetro por sessão, então você pode gerenciar seu produto na granularidade do recurso agent e seus usuários na granularidade do recurso session.



Criar um vault

Um vault é 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 aos 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)
echo "$VAULT_ID"  # "vlt_01ABC..."

A resposta é o registro completo do vault:

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

Duas categorias de credenciais são suportadas:

• Credenciais MCP (mcp_oauth, static_bearer): cada credencial é identificada por um mcp_server_url. Quando o agente se conecta a um servidor nessa URL em tempo de execução da sessão, o token é injetado automaticamente.
• Variáveis de ambiente (environment_variable): cada credencial é identificada por um secret_name (o nome da variável de ambiente) e armazenada no sandbox como um placeholder opaco. Quando o agente inicia uma requisição de saída, o placeholder opaco é substituído pelo segredo real na saída (egress). O agente nunca vê o valor do segredo. Use isso para qualquer serviço que autentique por meio de uma variável de ambiente, como CLIs, SDKs ou chamadas diretas de API.

Os valores reais de credencial que você fornece (token, access_token, refresh_token, client_secret, secret_value) são tratados como campos sensíveis, somente de escrita, e nunca são retornados nas respostas da API.

As credenciais são armazenadas conforme fornecidas e não são validadas até o tempo de execução da sessão. Uma credencial inválida aparece como um erro de autenticação ou erro downstream durante a sessão, que é emitido mas não impede a sessão de continuar.

Restrições:

• Chave única por vault. mcp_server_url (credenciais MCP) e secret_name (credenciais de variável de ambiente) devem ser únicos entre as credenciais ativas em um vault. Criar uma duplicata retorna um 409.
• Chaves são imutáveis. Para alterar mcp_server_url ou secret_name, arquive a credencial e crie uma nova.
• Máximo de 20 credenciais por vault.



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

Passe vault_ids ao criar uma sessão:

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)

Comportamento em tempo de execução:

• Quando nenhuma credencial MCP corresponde por mcp_server_url, a conexão é tentada sem autenticação e resultará em erro se o servidor exigir autenticação.
• Quando vários vaults contêm uma credencial correspondente, o primeiro vault com uma correspondência vence.
• Em sessões multiagente, as credenciais do vault se aplicam a todas as threads. Um agente cuja própria definição declara o servidor MCP correspondente autentica com essas credenciais. Consulte Conectar agentes a servidores MCP.



Rotacionar uma credencial

Valores de segredo, display_name e (em credenciais de variável de ambiente) injection_location podem ser atualizados. Atualizações de injection_location são mescladas por campo, conforme descrito na aba Variável de ambiente de Adicionar uma credencial. Para uma sessão em execução, uma atualização de injection_location se propaga da mesma forma que uma rotação de segredo: as credenciais da sessão são re-resolvidas sem reinicialização, conforme descrito em Ciclo de vida da credencial, e as localizações atualizadas se aplicam às requisições de saída subsequentes da sessão. Campos estruturais (mcp_server_url, secret_name, token_endpoint, client_id) são bloqueados após a criação. Para alterá-los, arquive a credencial e crie uma nova.

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



Ciclo de vida da credencial

As credenciais são re-resolvidas periodicamente, tanto durante uma sessão quanto durante o ciclo de vida do vault. Isso garante que a rotação, arquivamento ou exclusão de credenciais se propague para sessões em execução sem reinicialização.

Para ser notificado se uma credencial for arquivada, excluída ou falhar ao atualizar, você pode se inscrever nos webhooks de vault e credencial associados a essas mudanças de ciclo de vida.

Para credenciais mcp_oauth, a re-resolução também atualiza o access token se ele tiver expirado. Se o refresh falhar, um evento vault_credential.refresh_failed é emitido.



Diagnosticar uma falha de refresh OAuth

Para diagnosticar por que um refresh falhou, chame POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate (ou client.beta.vaults.credentials.mcp_oauth_validate(...) no SDK). Isso permite que você decida como lidar com a falha; a ação correta depende do tipo de erro.

O status de nível superior indica o que fazer a seguir:

• valid: o token funciona; nenhuma ação necessária.
• invalid: o grant foi perdido ou o servidor OAuth rejeitou o refresh com um 4xx. Solicite ao usuário final que reautorize.
• unknown: um erro transitório (5xx, 429 ou falha de rede). Aguarde e tente novamente.

ant beta:vaults:credentials mcp-oauth-validate \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" \
  --transform status --raw-output  # "valid", "invalid", or "unknown"

A resposta é um objeto vault_credential_validation. mcp_probe inclui a etapa de handshake MCP que falhou; refresh inclui o resultado da tentativa de 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
  }
}



Outras operações

• Listar vaults ou credenciais: Paginado, mais recentes primeiro. Registros arquivados são excluídos por padrão (passe include_archived=true para incluí-los).
• Arquivar um vault: POST /v1/vaults/{id}/archive. Propaga em cascata para todas as credenciais. Os segredos são eliminados; os registros são retidos para auditoria. Sessões futuras que referenciam este vault falham; sessões em execução continuam.
• Arquivar uma credencial: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Elimina o payload do segredo; a chave da credencial (mcp_server_url ou secret_name) permanece visível e é liberada para uma credencial substituta.
• Excluir um vault ou credencial: Exclusão permanente. O registro não é retido. Use arquivamento se você precisar de uma trilha de auditoria.