Authenticate with vaults

Vaults and credentials are authentication primitives that let you register credentials for third-party services once and reference them by ID at session creation. This means you don't need to run your own secret store, transmit tokens on every call, or lose track of which end user an agent acted on behalf of.

The vault reference is a per-session parameter, so you can manage your product at the agent level and your users at the session level.

Create a vault

A vault is the collection of credentials associated with an end user. Give it a display_name and optionally tag it with metadata so you can map it back to your own user records.

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

The response is the full vault record:

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

Add a credential

Each credential binds to a single mcp_server_url. When the agent connects to an MCP server at session runtime, the API matches the server URL against active credentials on the referenced vault and injects the token.

Credentials are stored as provided and are not validated until session runtime. A bad token surfaces as an MCP authentication error during the session, which is emitted but does not block the session from continuing.

Constraints:

• One active credential per mcp_server_url per vault. Creating a second credential for the same URL returns a 409.
• mcp_server_url is immutable. To point at a different server, archive this credential and create a new one.
• Maximum 20 credentials per vault. This matches the maximum number of MCP servers per agent.

Reference the vault at session creation

Pass vault_ids when creating a session:

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

Runtime behavior:

• When a vault has no credential for the MCP server, the connection is attempted unauthenticated and produces an error if the server requires authentication.
• When multiple vaults cover the MCP server, the first vault with a match wins.
• In multiagent sessions, vault credentials apply to every thread. An agent whose own definition declares the matching MCP server authenticates with these credentials. See Connect agents to MCP servers.

Credential refresh

Credentials are re-resolved periodically, both during a session and during the vault lifecycle. This ensures that credential rotation, archival, or deletion propagates to running sessions without a restart.

To be notified if a credential is archived, deleted, or fails to refresh, you can subscribe to the vault and credential webhooks associated with those lifecycle changes.

Diagnose an OAuth refresh failure

To diagnose why a refresh failed, use the /mcp_oauth_validate endpoint. This allows you to determine how to handle the failure, which is distinct by error type.

The top-level status tells you what to do next:

• valid: the token works; no action needed.
• invalid: the grant is gone or the OAuth server rejected the refresh with a 4xx. Prompt the end user to re-authorize.
• unknown: a transient error (5xx, 429, or network failure). Wait and retry.

curl --fail-with-body -sS -X POST \
  "https://api.anthropic.com/v1/vaults/$vault_id/credentials/$credential_id/mcp_oauth_validate?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

The response is a vault_credential_validation object. mcp_probe includes the failed MCP handshake step; refresh includes the outcome of the attempted 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
  }
}

Rotate a credential

Only the secret payload and a handful of metadata fields are mutable. mcp_server_url, token_endpoint, and client_id are locked after creation.

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

Other operations

• List vaults or credentials: Paginated, newest first. Archived records are excluded by default (pass include_archived=true to include them).
• Archive a vault: POST /v1/vaults/{id}/archive. Cascades to all credentials. Secrets are purged; records are retained for auditing. Future sessions referencing this vault fail; running sessions continue.
• Archive a credential: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Purges the secret payload; mcp_server_url remains visible. Frees the mcp_server_url for a replacement credential.
• Delete a vault or credential: Hard delete. The record is not retained. Use archive if you need an audit trail.