The whole hunk
from line 20, old and new numbered
/
lines
from line 20
2020
2121A 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.
2222
23<CodeGroup defaultLanguage="CLI">
23<CodeGroup>
2424 ```bash cURL
25 vault_id=$(curl --fail-with-body -sS https://api.anthropic.com/v1/vaults \
25 curl --fail-with-body -sS https://api.anthropic.com/v1/vaults \
2626 -H "x-api-key: $ANTHROPIC_API_KEY" \
2727 -H "anthropic-version: 2023-06-01" \
2828 -H "anthropic-beta: managed-agents-2026-04-01" \
2929 -H "content-type: application/json" \
30 --data @- <<'EOF' | jq -r '.id'
30 --data @- <<'EOF'
3131 {
3232 "display_name": "Alice",
3333 "metadata": {"external_user_id": "usr_abc123"}
3434 }
3535 EOF
36 )
37 echo "$vault_id" # "vlt_01ABC..."
3836 ```
3937
4038 <MultiFileExample language="cli" label="CLI">
4139 ```bash CLI
42 VAULT_ID=$(ant beta:vaults create --transform id --raw-output < alice.vault.yaml)
43 echo "$VAULT_ID" # "vlt_01ABC..."
40 ant beta:vaults create < alice.vault.yaml
4441 ```
4542
4643 <File filename="alice.vault.yaml">
from line 149
152149 * `client_secret_basic`: HTTP Basic authentication with the client secret
153150 * `client_secret_post`: client secret in the POST body
154151
155 <CodeGroup defaultLanguage="CLI">
152 <CodeGroup>
156153 ```bash cURL
157 credential_id=$(curl --fail-with-body -sS "https://api.anthropic.com/v1/vaults/$vault_id/credentials" \
154 curl --fail-with-body -sS "https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials" \
158155 -H "x-api-key: $ANTHROPIC_API_KEY" \
159156 -H "anthropic-version: 2023-06-01" \
160157 -H "anthropic-beta: managed-agents-2026-04-01" \
161158 -H "content-type: application/json" \
162 --data @- <<'EOF' | jq -r '.id'
159 --data @- <<'EOF'
163160 {
164161 "display_name": "Alice's Slack",
165162 "auth": {
from line 174
177174 }
178175 }
179176 EOF
180 )
181177 ```
182178
183179 ```bash CLI
184 CREDENTIAL_ID=$(ant beta:vaults:credentials create \
180 ant beta:vaults:credentials create \
185181 --vault-id "$VAULT_ID" \
186 --display-name "Alice's Slack" \
187 --transform id --raw-output <<'YAML'
182 --display-name "Alice's Slack" <<'YAML'
188183 auth:
189184 type: mcp_oauth
190185 mcp_server_url: https://mcp.slack.com/mcp
from line 194
199194 type: client_secret_post
200195 client_secret: abc123...
201196 YAML
202 )
203197 ```
204198
205199 ```python Python
from line 366
372366 <Tab title="MCP static bearer">
373367 Use `static_bearer` when the MCP server accepts a fixed bearer token (API key, personal access token, or similar). No refresh flow is needed.
374368
375 <CodeGroup defaultLanguage="CLI">
369 <CodeGroup>
376370 ```bash cURL
377 curl --fail-with-body -sS "https://api.anthropic.com/v1/vaults/$vault_id/credentials" \
371 curl --fail-with-body -sS "https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials" \
378372 -H "x-api-key: $ANTHROPIC_API_KEY" \
379373 -H "anthropic-version: 2023-06-01" \
380374 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 499
505499
506500 The optional `injection_location` field scopes where the secret is substituted; the full semantics follow the example.
507501
508 <CodeGroup defaultLanguage="CLI">
502 <CodeGroup>
509503 ```bash cURL
510 curl --fail-with-body -sS "https://api.anthropic.com/v1/vaults/$vault_id/credentials" \
504 curl --fail-with-body -sS "https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials" \
511505 -H "x-api-key: $ANTHROPIC_API_KEY" \
512506 -H "anthropic-version: 2023-06-01" \
513507 -H "anthropic-beta: managed-agents-2026-04-01" \
514508 -H "content-type: application/json" \
515 --data @- <<'EOF' | jq '.auth.injection_location'
509 --data @- <<'EOF'
516510 {
517511 "auth": {
518512 "type": "environment_variable",
from line 524
530524 ```
531525
532526 ```bash CLI
533 ant beta:vaults:credentials create \
534 --vault-id "$VAULT_ID" \
535 --transform 'auth.injection_location' --format json <<'YAML'
527 ant beta:vaults:credentials create --vault-id "$VAULT_ID" <<'YAML'
536528 display_name: Notion API key for sandbox
537529 auth:
538530 type: environment_variable
from line 735
743735
744736Pass `vault_ids` when creating a session:
745737
746<CodeGroup defaultLanguage="CLI">
738<CodeGroup>
747739 ```bash cURL
748 session_id=$(curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \
740 curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \
749741 -H "x-api-key: $ANTHROPIC_API_KEY" \
750742 -H "anthropic-version: 2023-06-01" \
751743 -H "anthropic-beta: managed-agents-2026-04-01" \
752744 -H "content-type: application/json" \
753 --data @- <<EOF | jq -r '.id'
745 --data @- <<EOF
754746 {
755 "agent": "$agent_id",
756 "environment_id": "$environment_id",
757 "vault_ids": ["$vault_id"],
747 "agent": "$AGENT_ID",
748 "environment_id": "$ENVIRONMENT_ID",
749 "vault_ids": ["$VAULT_ID"],
758750 "title": "Alice's Slack digest"
759751 }
760752 EOF
761 )
762753 ```
763754
764755 ```bash CLI
765 SESSION_ID=$(ant beta:sessions create \
756 ant beta:sessions create \
766757 --agent "$AGENT_ID" \
767758 --environment-id "$ENVIRONMENT_ID" \
768759 --vault-id "$VAULT_ID" \
769 --title "Alice's Slack digest" \
770 --transform id --raw-output)
760 --title "Alice's Slack digest"
771761 ```
772762
773763 ```python Python
from line 840
850840
851841Secret values, `display_name`, and (on environment variable credentials) `injection_location` can be updated. `injection_location` updates merge per field, as described in the Environment variable tab of [Add a credential](https://platform.claude.com/docs/en/managed-agents/vaults#add-a-credential). For a running session, an `injection_location` update propagates the same way as a secret rotation: the session's credentials are re-resolved without a restart, as described in [Credential lifecycle](https://platform.claude.com/docs/en/managed-agents/vaults#credential-lifecycle), and the updated locations apply to the session's subsequent outbound requests. Structural fields (`mcp_server_url`, `secret_name`, `token_endpoint`, `client_id`) are locked after creation. To change them, archive the credential and create a new one.
852842
853<CodeGroup defaultLanguage="CLI">
843<CodeGroup>
854844 ```bash cURL
855845 curl --fail-with-body -sS \
856 "https://api.anthropic.com/v1/vaults/$vault_id/credentials/$credential_id" \
846 "https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID" \
857847 -H "x-api-key: $ANTHROPIC_API_KEY" \
858848 -H "anthropic-version: 2023-06-01" \
859849 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 1005
10151005* `invalid`: the grant is gone or the OAuth server rejected the refresh with a 4xx. Prompt the end user to re-authorize.
10161006* `unknown`: a transient error (5xx, 429, or network failure). Wait and retry.
10171007
1018<CodeGroup defaultLanguage="CLI">
1008<CodeGroup>
10191009 ```bash cURL
10201010 curl --fail-with-body -sS -X POST \
1021 "https://api.anthropic.com/v1/vaults/$vault_id/credentials/$credential_id/mcp_oauth_validate?beta=true" \
1011 "https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/mcp_oauth_validate?beta=true" \
10221012 -H "x-api-key: $ANTHROPIC_API_KEY" \
10231013 -H "anthropic-version: 2023-06-01" \
10241014 -H "anthropic-beta: managed-agents-2026-04-01"
from line 1017
10271017 ```bash CLI
10281018 ant beta:vaults:credentials mcp-oauth-validate \
10291019 --vault-id "$VAULT_ID" \
1030 --credential-id "$CREDENTIAL_ID" \
1031 --transform status --raw-output # "valid", "invalid", or "unknown"
1020 --credential-id "$CREDENTIAL_ID"
10321021 ```
10331022
10341023 ```python Python