Autenticar com vaults

Vaults e credenciais são primitivas 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 atuou em nome.

A referência do 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 = client.beta.vaults.create(
    display_name="Alice",
    metadata={"external_user_id": "usr_abc123"},
)
print(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 é indexada por um mcp_server_url. Quando o agente se conecta a um servidor nessa URL no tempo de execução da sessão, o token é injetado automaticamente.
• Variáveis de ambiente (environment_variable): cada credencial é indexada 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. O agente nunca vê o valor do segredo. Use isso para qualquer serviço que autentique através de uma variável de ambiente, como CLIs, SDKs ou chamadas diretas de API.

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

credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Alice's Slack",
    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.user.access",
            "client_id": "1234567890.0987654321",
            "scope": "channels:read chat:write",
            "refresh_token": "xoxe-1-...",
            "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."},
        },
    },
)

bearer_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Linear API key",
    auth={
        "type": "static_bearer",
        "mcp_server_url": "https://mcp.linear.app/mcp",
        "token": "lin_api_your_linear_key",
    },
)

env_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Notion API key for sandbox",
    auth={
        "type": "environment_variable",
        "secret_name": "NOTION_API_KEY",
        "secret_value": "ntn_your-secret-here",
        "networking": {
            "type": "limited",
            "allowed_hosts": ["api.notion.com"],
        },
        "injection_location": {"header": True},
    },
)
if env_credential.auth.type == "environment_variable":
    location = env_credential.auth.injection_location
    print(f"header: {location.header}, body: {location.body}")  # header: True, body: False

As credenciais são armazenadas como 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 bloqueia a continuação da sessão.

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 = 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:

• 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 múltiplos 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 cada thread. 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. As atualizações de injection_location são mescladas por campo, conforme descrito na aba Environment variable 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.

client.beta.vaults.credentials.update(
    credential.id,
    vault_id=vault.id,
    auth={
        "type": "mcp_oauth",
        "access_token": "xoxp-new-...",
        "expires_at": "2099-12-31T23:59:59Z",
        "refresh": {"refresh_token": "xoxe-1-new-..."},
    },
)

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 token de acesso se ele tiver expirado. Se a atualização falhar, um evento vault_credential.refresh_failed é emitido.

Diagnosticar uma falha de atualização OAuth

Para diagnosticar por que uma atualização 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 informa o que fazer a seguir:

• valid: o token funciona; nenhuma ação necessária.
• invalid: a concessão desapareceu ou o servidor OAuth rejeitou a atualização 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.

validation = client.beta.vaults.credentials.mcp_oauth_validate(
    credential.id,
    vault_id=vault.id,
)
print(validation.status)  # "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 atualização tentada.

{
  "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. Cascateia para todas as credenciais. Os segredos são expurgados; 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. Expurga o payload do segredo; a chave da credencial (mcp_server_url ou secret_name) permanece visível e é liberada para uma credencial de substituição.
• Excluir um vault ou credencial: Exclusão permanente. O registro não é retido. Use arquivamento se você precisar de uma trilha de auditoria.