What this read moved
26–50 of 72This capture is too large to show at once. Changes 26-50 of 72 are below, significant first; the rest are on the following screens.
manage-claude/cmek-aws-kms Changed · +397 / -375 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 137
137137 To attach the key to an additional workspace, add that workspace's compartment ID to the condition with `kms:PutKeyPolicy` before attaching.
138138 </Note>
139139
140 <Steps>
141 <Step title="Register the key with Anthropic">
142 Create an external key configuration through the Admin API.
143
144 <CodeGroup>
145 ```bash cURL
146 curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \
147 -H "x-api-key: $ANTHROPIC_API_KEY" \
148 -H "anthropic-version: 2023-06-01" \
149 -H "content-type: application/json" \
150 -d '{
151 "display_name": "<friendly-name>",
152 "geo": "us",
153 "provider_config": {
154 "type": "aws",
155 "kms_arn": "<key-arn-from-create-key-step>"
140 You can set up the key in the Claude Console or through the Admin API, with the same result.
141
142 <Tabs>
143 <Tab title="Claude Console">
144 <Steps>
145 <Step title="Register the key with Anthropic">
146 In the Claude Console, open **Settings > Encryption keys** and click **Add key**. Enter a display name, choose **AWS KMS**, and click **Continue**. Paste the key ARN into **KMS key ARN**, and click **Add**.
147 </Step>
148
149 <Step title="Validate the key">
150 On the **Encryption keys** page, click **Verify** next to the key. **Connected** appears when the check passes. If it fails, a message gives the reason.
151 </Step>
152
153 <Step title="Attach the key to a workspace">
154 Open **Settings > Workspaces**, choose the workspace, and open its **Security** tab. Under **Encryption key**, select the key, click **Save**, and confirm. Attaching a key can't be undone. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
155 </Step>
156 </Steps>
157 </Tab>
158
159 <Tab title="API">
160 <Steps>
161 <Step title="Register the key with Anthropic">
162 Create an external key configuration through the Admin API.
163
164 <CodeGroup>
165 ```bash cURL
166 curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \
167 -H "x-api-key: $ANTHROPIC_API_KEY" \
168 -H "anthropic-version: 2023-06-01" \
169 -H "content-type: application/json" \
170 -d '{
171 "display_name": "<friendly-name>",
172 "geo": "us",
173 "provider_config": {
174 "type": "aws",
175 "kms_arn": "<key-arn-from-create-key-step>"
176 }
177 }'
178 ```
179
180 ```bash CLI
181 ant beta:organization:external-keys create <<'YAML'
182 display_name: "<friendly-name>"
183 geo: us
184 provider_config:
185 type: aws
186 kms_arn: "<key-arn-from-create-key-step>"
187 YAML
188 ```
189
190 ```python Python
191 client = anthropic.Anthropic()
192
193 external_key = client.beta.organization.external_keys.create(
194 display_name="<friendly-name>",
195 geo="us",
196 provider_config={"type": "aws", "kms_arn": "<key-arn-from-create-key-step>"},
197 )
198
199 print(f"id: {external_key.id}")
200 print(f"display_name: {external_key.display_name}")
201 ```
202
203 ```typescript TypeScript
204 const client = new Anthropic();
205
206 const externalKey = await client.beta.organization.externalKeys.create({
207 display_name: "<friendly-name>",
208 geo: "us",
209 provider_config: {
210 type: "aws",
211 kms_arn: "<key-arn-from-create-key-step>"
212 }
213 });
214
215 console.log(`id: ${externalKey.id}`);
216 console.log(`display_name: ${externalKey.display_name}`);
217 ```
218
219 ```csharp C#
220 using Anthropic.Models.Beta.Organization.ExternalKeys;
221
222 AnthropicClient client = new();
223
224 var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()
225 {
226 DisplayName = "<friendly-name>",
227 Geo = Geo.Us,
228 ProviderConfig = new BetaAwsExternalKeyConfig
229 {
230 KmsArn = "<key-arn-from-create-key-step>"
231 }
232 });
233
234 Console.WriteLine($"id: {externalKey.ID}");
235 Console.WriteLine($"display_name: {externalKey.DisplayName}");
236 ```
237
238 ```go Go
239 client := anthropic.NewClient()
240
241 externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{
242 DisplayName: anthropic.String("<friendly-name>"),
243 Geo: anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,
244 ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{
245 OfAWS: &anthropic.BetaAWSExternalKeyConfigParam{
246 KMSARN: "<key-arn-from-create-key-step>",
247 },
248 },
249 })
250 if err != nil {
251 log.Fatal(err)
156252 }
157 }'
158 ```
159
160 ```bash CLI
161 ant beta:organization:external-keys create <<'YAML'
162 display_name: "<friendly-name>"
163 geo: us
164 provider_config:
165 type: aws
166 kms_arn: "<key-arn-from-create-key-step>"
167 YAML
168 ```
169
170 ```python Python
171 client = anthropic.Anthropic()
172
173 external_key = client.beta.organization.external_keys.create(
174 display_name="<friendly-name>",
175 geo="us",
176 provider_config={"type": "aws", "kms_arn": "<key-arn-from-create-key-step>"},
177 )
178
179 print(f"id: {external_key.id}")
180 print(f"display_name: {external_key.display_name}")
181 ```
182
183 ```typescript TypeScript
184 const client = new Anthropic();
185
186 const externalKey = await client.beta.organization.externalKeys.create({
187 display_name: "<friendly-name>",
188 geo: "us",
189 provider_config: {
190 type: "aws",
191 kms_arn: "<key-arn-from-create-key-step>"
253
254 fmt.Printf("id: %s\n", externalKey.ID)
255 fmt.Printf("display_name: %s\n", externalKey.DisplayName)
256 ```
257
258 ```java Java
259 import com.anthropic.models.beta.organization.externalkeys.BetaAwsExternalKeyConfig;
260 import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;
261
262 void main() {
263 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
264
265 var params = ExternalKeyCreateParams.builder()
266 .displayName("<friendly-name>")
267 .geo(ExternalKeyCreateParams.Geo.US)
268 .providerConfig(BetaAwsExternalKeyConfig.builder()
269 .kmsArn("<key-arn-from-create-key-step>")
270 .build())
271 .build();
272 var externalKey = client.beta().organization().externalKeys().create(params);
273
274 IO.println("id: " + externalKey.id());
275 IO.println("display_name: " + externalKey.displayName().orElseThrow());
276 }
277 ```
278
279 ```php PHP
280 use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;
281 // ...
282
283 $client = new Client();
284
285 $externalKey = $client->beta->organization->externalKeys->create(
286 displayName: '<friendly-name>',
287 geo: Geo::US,
288 providerConfig: [
289 'type' => 'aws',
290 'kmsARN' => '<key-arn-from-create-key-step>',
291 ],
292 );
293
294 echo "id: {$externalKey->id}\n";
295 echo "display_name: {$externalKey->displayName}\n";
296 ```
297
298 ```ruby Ruby
299 client = Anthropic::Client.new
300
301 external_key = client.beta.organization.external_keys.create(
302 display_name: "<friendly-name>",
303 geo: :us,
304 provider_config: {
305 type: :aws,
306 kms_arn: "<key-arn-from-create-key-step>"
307 }
308 )
309
310 puts "id: #{external_key.id}"
311 puts "display_name: #{external_key.display_name}"
312 ```
313 </CodeGroup>
314
315 The response contains the external key ID:
316
317 ```json
318 {
319 "type": "external_key",
320 "id": "ekey_<id>",
321 "display_name": "<friendly-name>"
192322 }
193 });
194
195 console.log(`id: ${externalKey.id}`);
196 console.log(`display_name: ${externalKey.display_name}`);
197 ```
198
199 ```csharp C#
200 using Anthropic.Models.Beta.Organization.ExternalKeys;
201
202 AnthropicClient client = new();
203
204 var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()
205 {
206 DisplayName = "<friendly-name>",
207 Geo = Geo.Us,
208 ProviderConfig = new BetaAwsExternalKeyConfig
323 ```
324 </Step>
325
326 <Step title="Validate the key">
327 Trigger an encrypt and decrypt round-trip against your key.
328
329 <CodeGroup>
330 ```bash cURL
331 curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \
332 -H "x-api-key: $ANTHROPIC_API_KEY" \
333 -H "anthropic-version: 2023-06-01"
334 ```
335
336 ```bash CLI
337 ant beta:organization:external-keys validate --external-key-id "ekey_<id>"
338 ```
339
340 ```python Python
341 client = anthropic.Anthropic()
342
343 validation = client.beta.organization.external_keys.validate("ekey_<id>")
344
345 print(f"status: {validation.status}")
346 print(f"error: {validation.error}")
347 ```
348
349 ```typescript TypeScript
350 const client = new Anthropic();
351
352 const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");
353
354 console.log(`status: ${validation.status}`);
355 console.log(`error: ${validation.error}`);
356 ```
357
358 ```csharp C#
359 AnthropicClient client = new();
360
361 var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");
362
363 Console.WriteLine($"status: {validation.Status.Raw()}");
364 Console.WriteLine($"error: {validation.Error}");
365 ```
366
367 ```go Go
368 client := anthropic.NewClient()
369
370 validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")
371 if err != nil {
372 log.Fatal(err)
373 }
374
375 fmt.Printf("status: %s\n", validation.Status)
376 fmt.Printf("error: %s\n", validation.Error)
377 ```
378
379 ```java Java
380 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
381
382 var validation = client.beta().organization().externalKeys().validate("ekey_<id>");
383
384 IO.println("status: " + validation.status().asString());
385 IO.println("error: " + validation.error().orElse(""));
386 ```
387
388 ```php PHP
389 $client = new Client();
390
391 $validation = $client->beta->organization->externalKeys->validate(
392 externalKeyID: 'ekey_<id>',
393 );
394
395 echo "status: {$validation->status}\n";
396 echo "error: {$validation->error}\n";
397 ```
398
399 ```ruby Ruby
400 client = Anthropic::Client.new
401
402 external_key_id = "ekey_<id>"
403 validation = client.beta.organization.external_keys.validate(external_key_id)
404
405 puts "status: #{validation.status}"
406 puts "error: #{validation.error}"
407 ```
408 </CodeGroup>
409
410 A successful response looks like this:
411
412 ```json
413 { "type": "external_key_validation", "status": "success", "error": null }
414 ```
415
416 If validation fails, common causes are:
417
418 * **Encryption context mismatch:** Validation fails while data traffic works (or the reverse) with an opaque `AccessDeniedException` when a `kms:EncryptionContext:anthropic:compartment_uuid` condition allows only one of the two values Anthropic sends. Validation sends the all-zeros UUID (`00000000-0000-0000-0000-000000000000`); live traffic sends the attached workspace's compartment ID. Confirm the condition lists both. To rule the condition out entirely, temporarily remove the `Condition` block from the `AllowAnthropicCMEKCrypto` statement and re-validate.
419 * **Resource control policies (RCPs):** If your AWS organization has an RCP that denies KMS operations when `aws:PrincipalOrgID` does not match your org, it blocks Anthropic's cross-account role. The RCP needs a carve-out for this key or for Anthropic's role ARN. Service control policies do not apply here, because they do not evaluate for external principals calling through resource-based policies.
420 * **Access granted through IAM instead of the key policy:** Cross-account KMS access must be granted in the key policy itself, not through an IAM policy in your account. Check with `aws kms get-key-policy --key-id <id> --policy-name default`.
421 * **Region mismatch:** Confirm the key's region is one Anthropic operates in for the geo tier you configured.
422 </Step>
423
424 <Step title="Attach the key to a workspace">
425 Once the key is validated, attach it to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
426
427 <CodeGroup>
428 ```bash cURL
429 curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \
430 -H "x-api-key: $ANTHROPIC_API_KEY" \
431 -H "anthropic-version: 2023-06-01" \
432 -H "content-type: application/json" \
433 -d '{
434 "external_key_id": "ekey_<id>"
435 }'
436 ```
437
438 ```bash CLI
439 ant beta:organization:workspaces update \
440 --workspace-id "<workspace-id>" \
441 --external-key-id "ekey_<id>"
442 ```
443
444 ```python Python
445 client = anthropic.Anthropic()
446
447 workspace = client.beta.organization.workspaces.update(
448 "<workspace-id>", external_key_id="ekey_<id>"
449 )
450
451 print(f"id: {workspace.id}")
452 print(f"external_key_id: {workspace.external_key_id}")
453 ```
454
455 ```typescript TypeScript
456 const client = new Anthropic();
457
458 const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {
459 external_key_id: "ekey_<id>"
460 });
461
462 console.log(`id: ${workspace.id}`);
463 console.log(`external_key_id: ${workspace.external_key_id}`);
464 ```
465
466 ```csharp C#
467 AnthropicClient client = new();
468
469 var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()
209470 {
210 KmsArn = "<key-arn-from-create-key-step>"
471 ExternalKeyID = "ekey_<id>"
472 });
473
474 Console.WriteLine($"id: {workspace.ID}");
475 Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");
476 ```
477
478 ```go Go
479 client := anthropic.NewClient()
480
481 workspace, err := client.Beta.Organization.Workspaces.Update(
482 context.Background(),
483 "<workspace-id>",
484 anthropic.BetaOrganizationWorkspaceUpdateParams{
485 ExternalKeyID: anthropic.String("ekey_<id>"),
486 },
487 )
488 if err != nil {
489 log.Fatal(err)
211490 }
212 });
213
214 Console.WriteLine($"id: {externalKey.ID}");
215 Console.WriteLine($"display_name: {externalKey.DisplayName}");
216 ```
217
218 ```go Go
219 client := anthropic.NewClient()
220
221 externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{
222 DisplayName: anthropic.String("<friendly-name>"),
223 Geo: anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,
224 ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{
225 OfAWS: &anthropic.BetaAWSExternalKeyConfigParam{
226 KMSARN: "<key-arn-from-create-key-step>",
227 },
228 },
229 })
230 if err != nil {
231 log.Fatal(err)
232 }
233
234 fmt.Printf("id: %s\n", externalKey.ID)
235 fmt.Printf("display_name: %s\n", externalKey.DisplayName)
236 ```
237
238 ```java Java
239 import com.anthropic.models.beta.organization.externalkeys.BetaAwsExternalKeyConfig;
240 import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;
241
242 void main() {
243 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
244
245 var params = ExternalKeyCreateParams.builder()
246 .displayName("<friendly-name>")
247 .geo(ExternalKeyCreateParams.Geo.US)
248 .providerConfig(BetaAwsExternalKeyConfig.builder()
249 .kmsArn("<key-arn-from-create-key-step>")
250 .build())
251 .build();
252 var externalKey = client.beta().organization().externalKeys().create(params);
253
254 IO.println("id: " + externalKey.id());
255 IO.println("display_name: " + externalKey.displayName().orElseThrow());
256 }
257 ```
258
259 ```php PHP
260 use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;
261 // ...
262
263 $client = new Client();
264
265 $externalKey = $client->beta->organization->externalKeys->create(
266 displayName: '<friendly-name>',
267 geo: Geo::US,
268 providerConfig: [
269 'type' => 'aws',
270 'kmsARN' => '<key-arn-from-create-key-step>',
271 ],
272 );
273
274 echo "id: {$externalKey->id}\n";
275 echo "display_name: {$externalKey->displayName}\n";
276 ```
277
278 ```ruby Ruby
279 client = Anthropic::Client.new
280
281 external_key = client.beta.organization.external_keys.create(
282 display_name: "<friendly-name>",
283 geo: :us,
284 provider_config: {
285 type: :aws,
286 kms_arn: "<key-arn-from-create-key-step>"
287 }
288 )
289
290 puts "id: #{external_key.id}"
291 puts "display_name: #{external_key.display_name}"
292 ```
293 </CodeGroup>
294
295 The response contains the external key ID:
296
297 ```json
298 {
299 "type": "external_key",
300 "id": "ekey_<id>",
301 "display_name": "<friendly-name>"
302 }
303 ```
304 </Step>
305
306 <Step title="Validate the key">
307 Trigger an encrypt and decrypt round-trip against your key.
308
309 <CodeGroup>
310 ```bash cURL
311 curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \
312 -H "x-api-key: $ANTHROPIC_API_KEY" \
313 -H "anthropic-version: 2023-06-01"
314 ```
315
316 ```bash CLI
317 ant beta:organization:external-keys validate --external-key-id "ekey_<id>"
318 ```
319
320 ```python Python
321 client = anthropic.Anthropic()
322
323 validation = client.beta.organization.external_keys.validate("ekey_<id>")
324
325 print(f"status: {validation.status}")
326 print(f"error: {validation.error}")
327 ```
328
329 ```typescript TypeScript
330 const client = new Anthropic();
331
332 const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");
333
334 console.log(`status: ${validation.status}`);
335 console.log(`error: ${validation.error}`);
336 ```
337
338 ```csharp C#
339 AnthropicClient client = new();
340
341 var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");
342
343 Console.WriteLine($"status: {validation.Status.Raw()}");
344 Console.WriteLine($"error: {validation.Error}");
345 ```
346
347 ```go Go
348 client := anthropic.NewClient()
349
350 validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")
351 if err != nil {
352 log.Fatal(err)
353 }
354
355 fmt.Printf("status: %s\n", validation.Status)
356 fmt.Printf("error: %s\n", validation.Error)
357 ```
358
359 ```java Java
360 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
361
362 var validation = client.beta().organization().externalKeys().validate("ekey_<id>");
363
364 IO.println("status: " + validation.status().asString());
365 IO.println("error: " + validation.error().orElse(""));
366 ```
367
368 ```php PHP
369 $client = new Client();
370
371 $validation = $client->beta->organization->externalKeys->validate(
372 externalKeyID: 'ekey_<id>',
373 );
374
375 echo "status: {$validation->status}\n";
376 echo "error: {$validation->error}\n";
377 ```
378
379 ```ruby Ruby
380 client = Anthropic::Client.new
381
382 external_key_id = "ekey_<id>"
383 validation = client.beta.organization.external_keys.validate(external_key_id)
384
385 puts "status: #{validation.status}"
386 puts "error: #{validation.error}"
387 ```
388 </CodeGroup>
389
390 A successful response looks like this:
391
392 ```json
393 { "type": "external_key_validation", "status": "success", "error": null }
394 ```
395
396 If validation fails, common causes are:
397
398 * **Encryption context mismatch:** Validation fails while data traffic works (or the reverse) with an opaque `AccessDeniedException` when a `kms:EncryptionContext:anthropic:compartment_uuid` condition allows only one of the two values Anthropic sends. Validation sends the all-zeros UUID (`00000000-0000-0000-0000-000000000000`); live traffic sends the attached workspace's compartment ID. Confirm the condition lists both. To rule the condition out entirely, temporarily remove the `Condition` block from the `AllowAnthropicCMEKCrypto` statement and re-validate.
399 * **Resource control policies (RCPs):** If your AWS organization has an RCP that denies KMS operations when `aws:PrincipalOrgID` does not match your org, it blocks Anthropic's cross-account role. The RCP needs a carve-out for this key or for Anthropic's role ARN. Service control policies do not apply here, because they do not evaluate for external principals calling through resource-based policies.
400 * **Access granted through IAM instead of the key policy:** Cross-account KMS access must be granted in the key policy itself, not through an IAM policy in your account. Check with `aws kms get-key-policy --key-id <id> --policy-name default`.
401 * **Region mismatch:** Confirm the key's region is one Anthropic operates in for the geo tier you configured.
402 </Step>
403
404 <Step title="Attach the key to a workspace">
405 Once the key is validated, attach it to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
406
407 <CodeGroup>
408 ```bash cURL
409 curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \
410 -H "x-api-key: $ANTHROPIC_API_KEY" \
411 -H "anthropic-version: 2023-06-01" \
412 -H "content-type: application/json" \
413 -d '{
414 "external_key_id": "ekey_<id>"
415 }'
416 ```
417
418 ```bash CLI
419 ant beta:organization:workspaces update \
420 --workspace-id "<workspace-id>" \
421 --external-key-id "ekey_<id>"
422 ```
423
424 ```python Python
425 client = anthropic.Anthropic()
426
427 workspace = client.beta.organization.workspaces.update(
428 "<workspace-id>", external_key_id="ekey_<id>"
429 )
430
431 print(f"id: {workspace.id}")
432 print(f"external_key_id: {workspace.external_key_id}")
433 ```
434
435 ```typescript TypeScript
436 const client = new Anthropic();
437
438 const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {
439 external_key_id: "ekey_<id>"
440 });
441
442 console.log(`id: ${workspace.id}`);
443 console.log(`external_key_id: ${workspace.external_key_id}`);
444 ```
445
446 ```csharp C#
447 AnthropicClient client = new();
448
449 var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()
450 {
451 ExternalKeyID = "ekey_<id>"
452 });
453
454 Console.WriteLine($"id: {workspace.ID}");
455 Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");
456 ```
457
458 ```go Go
459 client := anthropic.NewClient()
460
461 workspace, err := client.Beta.Organization.Workspaces.Update(
462 context.Background(),
463 "<workspace-id>",
464 anthropic.BetaOrganizationWorkspaceUpdateParams{
465 ExternalKeyID: anthropic.String("ekey_<id>"),
466 },
467 )
468 if err != nil {
469 log.Fatal(err)
470 }
471
472 fmt.Printf("id: %s\n", workspace.ID)
473 fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)
474 ```
475
476 ```java Java
477 import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;
478
479 void main() {
480 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
481
482 var params = WorkspaceUpdateParams.builder()
483 .externalKeyId("ekey_<id>")
484 .build();
485 var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);
486
487 IO.println("id: " + workspace.id());
488 IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());
489 }
490 ```
491
492 ```php PHP
493 $client = new Client();
494
495 $workspace = $client->beta->organization->workspaces->update(
496 workspaceID: '<workspace-id>',
497 externalKeyID: 'ekey_<id>',
498 );
499
500 echo "id: {$workspace->id}\n";
501 echo "external_key_id: {$workspace->externalKeyID}\n";
502 ```
503
504 ```ruby Ruby
505 client = Anthropic::Client.new
506
507 workspace_id = "<workspace-id>"
508 workspace = client.beta.organization.workspaces.update(
509 workspace_id,
510 external_key_id: "ekey_<id>"
511 )
512
513 puts "id: #{workspace.id}"
514 puts "external_key_id: #{workspace.external_key_id}"
515 ```
516 </CodeGroup>
517 </Step>
518 </Steps>
491
492 fmt.Printf("id: %s\n", workspace.ID)
493 fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)
494 ```
495
496 ```java Java
497 import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;
498
499 void main() {
500 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
501
502 var params = WorkspaceUpdateParams.builder()
503 .externalKeyId("ekey_<id>")
504 .build();
505 var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);
506
507 IO.println("id: " + workspace.id());
508 IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());
509 }
510 ```
511
512 ```php PHP
513 $client = new Client();
514
515 $workspace = $client->beta->organization->workspaces->update(
516 workspaceID: '<workspace-id>',
517 externalKeyID: 'ekey_<id>',
518 );
519
520 echo "id: {$workspace->id}\n";
521 echo "external_key_id: {$workspace->externalKeyID}\n";
522 ```
523
524 ```ruby Ruby
525 client = Anthropic::Client.new
526
527 workspace_id = "<workspace-id>"
528 workspace = client.beta.organization.workspaces.update(
529 workspace_id,
530 external_key_id: "ekey_<id>"
531 )
532
533 puts "id: #{workspace.id}"
534 puts "external_key_id: #{workspace.external_key_id}"
535 ```
536 </CodeGroup>
537 </Step>
538 </Steps>
539 </Tab>
540 </Tabs>
519541 </Tab>
520542
521543 <Tab title="Claude Enterprise">
522544
manage-claude/cmek-azure-key-vault Changed · +415 / -393 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 143
143143
144144<Tabs>
145145 <Tab title="Claude Platform">
146 <Steps>
147 <Step title="Register the key with Anthropic">
148 Create an external key configuration through the Admin API.
149
150 <CodeGroup>
151 ```bash cURL
152 curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \
153 -H "x-api-key: $ANTHROPIC_API_KEY" \
154 -H "anthropic-version: 2023-06-01" \
155 -H "content-type: application/json" \
156 -d '{
157 "display_name": "<friendly-name>",
158 "geo": "us",
159 "provider_config": {
160 "type": "azure",
161 "vault_uri": "https://<your-vault-name>.vault.azure.net/",
162 "key_name": "<your-key-name>",
163 "tenant_id": "<your-tenant-id>"
146 You can set up the key in the Claude Console or through the Admin API, with the same result.
147
148 <Tabs>
149 <Tab title="Claude Console">
150 <Steps>
151 <Step title="Register the key with Anthropic">
152 In the Claude Console, open **Settings > Encryption keys** and click **Add key**. Enter a display name, choose **Azure Key Vault**, and click **Continue**. Fill in **Vault URI**, **Key name**, and **Tenant ID**, and click **Add**.
153 </Step>
154
155 <Step title="Validate the key">
156 On the **Encryption keys** page, click **Verify** next to the key. **Connected** appears when the check passes. If it fails, a message gives the reason.
157 </Step>
158
159 <Step title="Attach the key to a workspace">
160 Open **Settings > Workspaces**, choose the workspace, and open its **Security** tab. Under **Encryption key**, select the key, click **Save**, and confirm. Attaching a key can't be undone. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
161 </Step>
162 </Steps>
163 </Tab>
164
165 <Tab title="API">
166 <Steps>
167 <Step title="Register the key with Anthropic">
168 Create an external key configuration through the Admin API.
169
170 <CodeGroup>
171 ```bash cURL
172 curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \
173 -H "x-api-key: $ANTHROPIC_API_KEY" \
174 -H "anthropic-version: 2023-06-01" \
175 -H "content-type: application/json" \
176 -d '{
177 "display_name": "<friendly-name>",
178 "geo": "us",
179 "provider_config": {
180 "type": "azure",
181 "vault_uri": "https://<your-vault-name>.vault.azure.net/",
182 "key_name": "<your-key-name>",
183 "tenant_id": "<your-tenant-id>"
184 }
185 }'
186 ```
187
188 ```bash CLI
189 ant beta:organization:external-keys create <<'YAML'
190 display_name: "<friendly-name>"
191 geo: us
192 provider_config:
193 type: azure
194 vault_uri: "https://<your-vault-name>.vault.azure.net/"
195 key_name: "<your-key-name>"
196 tenant_id: "<your-tenant-id>"
197 YAML
198 ```
199
200 ```python Python
201 client = anthropic.Anthropic()
202
203 external_key = client.beta.organization.external_keys.create(
204 display_name="<friendly-name>",
205 geo="us",
206 provider_config={
207 "type": "azure",
208 "vault_uri": "https://<your-vault-name>.vault.azure.net/",
209 "key_name": "<your-key-name>",
210 "tenant_id": "<your-tenant-id>",
211 },
212 )
213
214 print(f"id: {external_key.id}")
215 print(f"display_name: {external_key.display_name}")
216 ```
217
218 ```typescript TypeScript
219 const client = new Anthropic();
220
221 const externalKey = await client.beta.organization.externalKeys.create({
222 display_name: "<friendly-name>",
223 geo: "us",
224 provider_config: {
225 type: "azure",
226 vault_uri: "https://<your-vault-name>.vault.azure.net/",
227 key_name: "<your-key-name>",
228 tenant_id: "<your-tenant-id>"
229 }
230 });
231
232 console.log(`id: ${externalKey.id}`);
233 console.log(`display_name: ${externalKey.display_name}`);
234 ```
235
236 ```csharp C#
237 using Anthropic.Models.Beta.Organization.ExternalKeys;
238
239 AnthropicClient client = new();
240
241 var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()
242 {
243 DisplayName = "<friendly-name>",
244 Geo = Geo.Us,
245 ProviderConfig = new BetaAzureExternalKeyConfigParam
246 {
247 VaultUri = "https://<your-vault-name>.vault.azure.net/",
248 KeyName = "<your-key-name>",
249 TenantID = "<your-tenant-id>"
250 }
251 });
252
253 Console.WriteLine($"id: {externalKey.ID}");
254 Console.WriteLine($"display_name: {externalKey.DisplayName}");
255 ```
256
257 ```go Go
258 client := anthropic.NewClient()
259
260 externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{
261 DisplayName: anthropic.String("<friendly-name>"),
262 Geo: anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,
263 ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{
264 OfAzure: &anthropic.BetaAzureExternalKeyConfigParam{
265 VaultURI: "https://<your-vault-name>.vault.azure.net/",
266 KeyName: "<your-key-name>",
267 TenantID: "<your-tenant-id>",
268 },
269 },
270 })
271 if err != nil {
272 log.Fatal(err)
164273 }
165 }'
166 ```
167
168 ```bash CLI
169 ant beta:organization:external-keys create <<'YAML'
170 display_name: "<friendly-name>"
171 geo: us
172 provider_config:
173 type: azure
174 vault_uri: "https://<your-vault-name>.vault.azure.net/"
175 key_name: "<your-key-name>"
176 tenant_id: "<your-tenant-id>"
177 YAML
178 ```
179
180 ```python Python
181 client = anthropic.Anthropic()
182
183 external_key = client.beta.organization.external_keys.create(
184 display_name="<friendly-name>",
185 geo="us",
186 provider_config={
187 "type": "azure",
188 "vault_uri": "https://<your-vault-name>.vault.azure.net/",
189 "key_name": "<your-key-name>",
190 "tenant_id": "<your-tenant-id>",
191 },
192 )
193
194 print(f"id: {external_key.id}")
195 print(f"display_name: {external_key.display_name}")
196 ```
197
198 ```typescript TypeScript
199 const client = new Anthropic();
200
201 const externalKey = await client.beta.organization.externalKeys.create({
202 display_name: "<friendly-name>",
203 geo: "us",
204 provider_config: {
205 type: "azure",
206 vault_uri: "https://<your-vault-name>.vault.azure.net/",
207 key_name: "<your-key-name>",
208 tenant_id: "<your-tenant-id>"
274
275 fmt.Printf("id: %s\n", externalKey.ID)
276 fmt.Printf("display_name: %s\n", externalKey.DisplayName)
277 ```
278
279 ```java Java
280 import com.anthropic.models.beta.organization.externalkeys.BetaAzureExternalKeyConfigParam;
281 import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;
282
283 void main() {
284 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
285
286 var params = ExternalKeyCreateParams.builder()
287 .displayName("<friendly-name>")
288 .geo(ExternalKeyCreateParams.Geo.US)
289 .providerConfig(BetaAzureExternalKeyConfigParam.builder()
290 .vaultUri("https://<your-vault-name>.vault.azure.net/")
291 .keyName("<your-key-name>")
292 .tenantId("<your-tenant-id>")
293 .build())
294 .build();
295 var externalKey = client.beta().organization().externalKeys().create(params);
296
297 IO.println("id: " + externalKey.id());
298 IO.println("display_name: " + externalKey.displayName().orElseThrow());
299 }
300 ```
301
302 ```php PHP
303 use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;
304 // ...
305
306 $client = new Client();
307
308 $externalKey = $client->beta->organization->externalKeys->create(
309 displayName: '<friendly-name>',
310 geo: Geo::US,
311 providerConfig: [
312 'type' => 'azure',
313 'vaultURI' => 'https://<your-vault-name>.vault.azure.net/',
314 'keyName' => '<your-key-name>',
315 'tenantID' => '<your-tenant-id>',
316 ],
317 );
318
319 echo "id: {$externalKey->id}\n";
320 echo "display_name: {$externalKey->displayName}\n";
321 ```
322
323 ```ruby Ruby
324 client = Anthropic::Client.new
325
326 external_key = client.beta.organization.external_keys.create(
327 display_name: "<friendly-name>",
328 geo: :us,
329 provider_config: {
330 type: :azure,
331 vault_uri: "https://<your-vault-name>.vault.azure.net/",
332 key_name: "<your-key-name>",
333 tenant_id: "<your-tenant-id>"
334 }
335 )
336
337 puts "id: #{external_key.id}"
338 puts "display_name: #{external_key.display_name}"
339 ```
340 </CodeGroup>
341
342 The response contains the external key ID:
343
344 ```json
345 {
346 "type": "external_key",
347 "id": "ekey_<id>",
348 "display_name": "<friendly-name>"
209349 }
210 });
211
212 console.log(`id: ${externalKey.id}`);
213 console.log(`display_name: ${externalKey.display_name}`);
214 ```
215
216 ```csharp C#
217 using Anthropic.Models.Beta.Organization.ExternalKeys;
218
219 AnthropicClient client = new();
220
221 var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()
222 {
223 DisplayName = "<friendly-name>",
224 Geo = Geo.Us,
225 ProviderConfig = new BetaAzureExternalKeyConfigParam
350 ```
351 </Step>
352
353 <Step title="Validate the key">
354 Trigger an encrypt and decrypt round-trip against your key. This confirms that Anthropic can authenticate to your tenant and perform wrap and unwrap operations.
355
356 <CodeGroup>
357 ```bash cURL
358 curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \
359 -H "x-api-key: $ANTHROPIC_API_KEY" \
360 -H "anthropic-version: 2023-06-01"
361 ```
362
363 ```bash CLI
364 ant beta:organization:external-keys validate --external-key-id "ekey_<id>"
365 ```
366
367 ```python Python
368 client = anthropic.Anthropic()
369
370 validation = client.beta.organization.external_keys.validate("ekey_<id>")
371
372 print(f"status: {validation.status}")
373 print(f"error: {validation.error}")
374 ```
375
376 ```typescript TypeScript
377 const client = new Anthropic();
378
379 const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");
380
381 console.log(`status: ${validation.status}`);
382 console.log(`error: ${validation.error}`);
383 ```
384
385 ```csharp C#
386 AnthropicClient client = new();
387
388 var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");
389
390 Console.WriteLine($"status: {validation.Status.Raw()}");
391 Console.WriteLine($"error: {validation.Error}");
392 ```
393
394 ```go Go
395 client := anthropic.NewClient()
396
397 validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")
398 if err != nil {
399 log.Fatal(err)
400 }
401
402 fmt.Printf("status: %s\n", validation.Status)
403 fmt.Printf("error: %s\n", validation.Error)
404 ```
405
406 ```java Java
407 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
408
409 var validation = client.beta().organization().externalKeys().validate("ekey_<id>");
410
411 IO.println("status: " + validation.status().asString());
412 IO.println("error: " + validation.error().orElse(""));
413 ```
414
415 ```php PHP
416 $client = new Client();
417
418 $validation = $client->beta->organization->externalKeys->validate(
419 externalKeyID: 'ekey_<id>',
420 );
421
422 echo "status: {$validation->status}\n";
423 echo "error: {$validation->error}\n";
424 ```
425
426 ```ruby Ruby
427 client = Anthropic::Client.new
428
429 validation = client.beta.organization.external_keys.validate("ekey_<id>")
430
431 puts "status: #{validation.status}"
432 puts "error: #{validation.error}"
433 ```
434 </CodeGroup>
435
436 A successful response looks like this:
437
438 ```json
439 { "type": "external_key_validation", "status": "success", "error": null }
440 ```
441
442 If validation fails, the `error` field describes the problem. Common causes are:
443
444 * **RBAC propagation delay:** role assignments can take a few minutes to take effect. Wait and retry.
445 * **Network ACLs blocking Anthropic:** confirm public network access and `ipRules` as described in the verification step.
446 * **Conditional access policies on workload identities:** if your tenant has conditional access policies that target service principals, exclude the Anthropic service principal or add Anthropic's egress ranges to the policy's named locations.
447 </Step>
448
449 <Step title="Attach the key to a workspace">
450 Once the key is validated, attach it to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
451
452 <CodeGroup>
453 ```bash cURL
454 curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \
455 -H "x-api-key: $ANTHROPIC_API_KEY" \
456 -H "anthropic-version: 2023-06-01" \
457 -H "content-type: application/json" \
458 -d '{
459 "external_key_id": "ekey_<id>"
460 }'
461 ```
462
463 ```bash CLI
464 ant beta:organization:workspaces update \
465 --workspace-id "<workspace-id>" \
466 --external-key-id "ekey_<id>"
467 ```
468
469 ```python Python
470 client = anthropic.Anthropic()
471
472 workspace = client.beta.organization.workspaces.update(
473 "<workspace-id>", external_key_id="ekey_<id>"
474 )
475
476 print(f"id: {workspace.id}")
477 print(f"external_key_id: {workspace.external_key_id}")
478 ```
479
480 ```typescript TypeScript
481 const client = new Anthropic();
482
483 const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {
484 external_key_id: "ekey_<id>"
485 });
486
487 console.log(`id: ${workspace.id}`);
488 console.log(`external_key_id: ${workspace.external_key_id}`);
489 ```
490
491 ```csharp C#
492 AnthropicClient client = new();
493
494 var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()
226495 {
227 VaultUri = "https://<your-vault-name>.vault.azure.net/",
228 KeyName = "<your-key-name>",
229 TenantID = "<your-tenant-id>"
496 ExternalKeyID = "ekey_<id>"
497 });
498
499 Console.WriteLine($"id: {workspace.ID}");
500 Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");
501 ```
502
503 ```go Go
504 client := anthropic.NewClient()
505
506 workspace, err := client.Beta.Organization.Workspaces.Update(
507 context.Background(),
508 "<workspace-id>",
509 anthropic.BetaOrganizationWorkspaceUpdateParams{
510 ExternalKeyID: anthropic.String("ekey_<id>"),
511 },
512 )
513 if err != nil {
514 log.Fatal(err)
230515 }
231 });
232
233 Console.WriteLine($"id: {externalKey.ID}");
234 Console.WriteLine($"display_name: {externalKey.DisplayName}");
235 ```
236
237 ```go Go
238 client := anthropic.NewClient()
239
240 externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{
241 DisplayName: anthropic.String("<friendly-name>"),
242 Geo: anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,
243 ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{
244 OfAzure: &anthropic.BetaAzureExternalKeyConfigParam{
245 VaultURI: "https://<your-vault-name>.vault.azure.net/",
246 KeyName: "<your-key-name>",
247 TenantID: "<your-tenant-id>",
248 },
249 },
250 })
251 if err != nil {
252 log.Fatal(err)
253 }
254
255 fmt.Printf("id: %s\n", externalKey.ID)
256 fmt.Printf("display_name: %s\n", externalKey.DisplayName)
257 ```
258
259 ```java Java
260 import com.anthropic.models.beta.organization.externalkeys.BetaAzureExternalKeyConfigParam;
261 import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;
262
263 void main() {
264 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
265
266 var params = ExternalKeyCreateParams.builder()
267 .displayName("<friendly-name>")
268 .geo(ExternalKeyCreateParams.Geo.US)
269 .providerConfig(BetaAzureExternalKeyConfigParam.builder()
270 .vaultUri("https://<your-vault-name>.vault.azure.net/")
271 .keyName("<your-key-name>")
272 .tenantId("<your-tenant-id>")
273 .build())
274 .build();
275 var externalKey = client.beta().organization().externalKeys().create(params);
276
277 IO.println("id: " + externalKey.id());
278 IO.println("display_name: " + externalKey.displayName().orElseThrow());
279 }
280 ```
281
282 ```php PHP
283 use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;
284 // ...
285
286 $client = new Client();
287
288 $externalKey = $client->beta->organization->externalKeys->create(
289 displayName: '<friendly-name>',
290 geo: Geo::US,
291 providerConfig: [
292 'type' => 'azure',
293 'vaultURI' => 'https://<your-vault-name>.vault.azure.net/',
294 'keyName' => '<your-key-name>',
295 'tenantID' => '<your-tenant-id>',
296 ],
297 );
298
299 echo "id: {$externalKey->id}\n";
300 echo "display_name: {$externalKey->displayName}\n";
301 ```
302
303 ```ruby Ruby
304 client = Anthropic::Client.new
305
306 external_key = client.beta.organization.external_keys.create(
307 display_name: "<friendly-name>",
308 geo: :us,
309 provider_config: {
310 type: :azure,
311 vault_uri: "https://<your-vault-name>.vault.azure.net/",
312 key_name: "<your-key-name>",
313 tenant_id: "<your-tenant-id>"
314 }
315 )
316
317 puts "id: #{external_key.id}"
318 puts "display_name: #{external_key.display_name}"
319 ```
320 </CodeGroup>
321
322 The response contains the external key ID:
323
324 ```json
325 {
326 "type": "external_key",
327 "id": "ekey_<id>",
328 "display_name": "<friendly-name>"
329 }
330 ```
331 </Step>
332
333 <Step title="Validate the key">
334 Trigger an encrypt and decrypt round-trip against your key. This confirms that Anthropic can authenticate to your tenant and perform wrap and unwrap operations.
335
336 <CodeGroup>
337 ```bash cURL
338 curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \
339 -H "x-api-key: $ANTHROPIC_API_KEY" \
340 -H "anthropic-version: 2023-06-01"
341 ```
342
343 ```bash CLI
344 ant beta:organization:external-keys validate --external-key-id "ekey_<id>"
345 ```
346
347 ```python Python
348 client = anthropic.Anthropic()
349
350 validation = client.beta.organization.external_keys.validate("ekey_<id>")
351
352 print(f"status: {validation.status}")
353 print(f"error: {validation.error}")
354 ```
355
356 ```typescript TypeScript
357 const client = new Anthropic();
358
359 const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");
360
361 console.log(`status: ${validation.status}`);
362 console.log(`error: ${validation.error}`);
363 ```
364
365 ```csharp C#
366 AnthropicClient client = new();
367
368 var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");
369
370 Console.WriteLine($"status: {validation.Status.Raw()}");
371 Console.WriteLine($"error: {validation.Error}");
372 ```
373
374 ```go Go
375 client := anthropic.NewClient()
376
377 validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")
378 if err != nil {
379 log.Fatal(err)
380 }
381
382 fmt.Printf("status: %s\n", validation.Status)
383 fmt.Printf("error: %s\n", validation.Error)
384 ```
385
386 ```java Java
387 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
388
389 var validation = client.beta().organization().externalKeys().validate("ekey_<id>");
390
391 IO.println("status: " + validation.status().asString());
392 IO.println("error: " + validation.error().orElse(""));
393 ```
394
395 ```php PHP
396 $client = new Client();
397
398 $validation = $client->beta->organization->externalKeys->validate(
399 externalKeyID: 'ekey_<id>',
400 );
401
402 echo "status: {$validation->status}\n";
403 echo "error: {$validation->error}\n";
404 ```
405
406 ```ruby Ruby
407 client = Anthropic::Client.new
408
409 validation = client.beta.organization.external_keys.validate("ekey_<id>")
410
411 puts "status: #{validation.status}"
412 puts "error: #{validation.error}"
413 ```
414 </CodeGroup>
415
416 A successful response looks like this:
417
418 ```json
419 { "type": "external_key_validation", "status": "success", "error": null }
420 ```
421
422 If validation fails, the `error` field describes the problem. Common causes are:
423
424 * **RBAC propagation delay:** role assignments can take a few minutes to take effect. Wait and retry.
425 * **Network ACLs blocking Anthropic:** confirm public network access and `ipRules` as described in the verification step.
426 * **Conditional access policies on workload identities:** if your tenant has conditional access policies that target service principals, exclude the Anthropic service principal or add Anthropic's egress ranges to the policy's named locations.
427 </Step>
428
429 <Step title="Attach the key to a workspace">
430 Once the key is validated, attach it to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
431
432 <CodeGroup>
433 ```bash cURL
434 curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \
435 -H "x-api-key: $ANTHROPIC_API_KEY" \
436 -H "anthropic-version: 2023-06-01" \
437 -H "content-type: application/json" \
438 -d '{
439 "external_key_id": "ekey_<id>"
440 }'
441 ```
442
443 ```bash CLI
444 ant beta:organization:workspaces update \
445 --workspace-id "<workspace-id>" \
446 --external-key-id "ekey_<id>"
447 ```
448
449 ```python Python
450 client = anthropic.Anthropic()
451
452 workspace = client.beta.organization.workspaces.update(
453 "<workspace-id>", external_key_id="ekey_<id>"
454 )
455
456 print(f"id: {workspace.id}")
457 print(f"external_key_id: {workspace.external_key_id}")
458 ```
459
460 ```typescript TypeScript
461 const client = new Anthropic();
462
463 const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {
464 external_key_id: "ekey_<id>"
465 });
466
467 console.log(`id: ${workspace.id}`);
468 console.log(`external_key_id: ${workspace.external_key_id}`);
469 ```
470
471 ```csharp C#
472 AnthropicClient client = new();
473
474 var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()
475 {
476 ExternalKeyID = "ekey_<id>"
477 });
478
479 Console.WriteLine($"id: {workspace.ID}");
480 Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");
481 ```
482
483 ```go Go
484 client := anthropic.NewClient()
485
486 workspace, err := client.Beta.Organization.Workspaces.Update(
487 context.Background(),
488 "<workspace-id>",
489 anthropic.BetaOrganizationWorkspaceUpdateParams{
490 ExternalKeyID: anthropic.String("ekey_<id>"),
491 },
492 )
493 if err != nil {
494 log.Fatal(err)
495 }
496
497 fmt.Printf("id: %s\n", workspace.ID)
498 fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)
499 ```
500
501 ```java Java
502 import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;
503
504 void main() {
505 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
506
507 var params = WorkspaceUpdateParams.builder()
508 .externalKeyId("ekey_<id>")
509 .build();
510 var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);
511
512 IO.println("id: " + workspace.id());
513 IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());
514 }
515 ```
516
517 ```php PHP
518 $client = new Client();
519
520 $workspace = $client->beta->organization->workspaces->update(
521 workspaceID: '<workspace-id>',
522 externalKeyID: 'ekey_<id>',
523 );
524
525 echo "id: {$workspace->id}\n";
526 echo "external_key_id: {$workspace->externalKeyID}\n";
527 ```
528
529 ```ruby Ruby
530 client = Anthropic::Client.new
531
532 workspace = client.beta.organization.workspaces.update(
533 "<workspace-id>",
534 external_key_id: "ekey_<id>"
535 )
536
537 puts "id: #{workspace.id}"
538 puts "external_key_id: #{workspace.external_key_id}"
539 ```
540 </CodeGroup>
541 </Step>
542 </Steps>
516
517 fmt.Printf("id: %s\n", workspace.ID)
518 fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)
519 ```
520
521 ```java Java
522 import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;
523
524 void main() {
525 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
526
527 var params = WorkspaceUpdateParams.builder()
528 .externalKeyId("ekey_<id>")
529 .build();
530 var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);
531
532 IO.println("id: " + workspace.id());
533 IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());
534 }
535 ```
536
537 ```php PHP
538 $client = new Client();
539
540 $workspace = $client->beta->organization->workspaces->update(
541 workspaceID: '<workspace-id>',
542 externalKeyID: 'ekey_<id>',
543 );
544
545 echo "id: {$workspace->id}\n";
546 echo "external_key_id: {$workspace->externalKeyID}\n";
547 ```
548
549 ```ruby Ruby
550 client = Anthropic::Client.new
551
552 workspace = client.beta.organization.workspaces.update(
553 "<workspace-id>",
554 external_key_id: "ekey_<id>"
555 )
556
557 puts "id: #{workspace.id}"
558 puts "external_key_id: #{workspace.external_key_id}"
559 ```
560 </CodeGroup>
561 </Step>
562 </Steps>
563 </Tab>
564 </Tabs>
543565 </Tab>
544566
545567 <Tab title="Claude Enterprise">
546568
manage-claude/cmek-google-cloud-kms Changed · +397 / -375 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 136
136136
137137<Tabs>
138138 <Tab title="Claude Platform">
139 <Steps>
140 <Step title="Register the key with Anthropic">
141 Create an external key configuration through the Admin API, using the resource name from the Note the full key resource name step under Encryption key setup.
142
143 <CodeGroup>
144 ```bash cURL
145 curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \
146 -H "x-api-key: $ANTHROPIC_API_KEY" \
147 -H "anthropic-version: 2023-06-01" \
148 -H "content-type: application/json" \
149 -d '{
150 "display_name": "<friendly-name>",
151 "geo": "us",
152 "provider_config": {
153 "type": "gcp",
154 "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
139 You can set up the key in the Claude Console or through the Admin API, with the same result.
140
141 <Tabs>
142 <Tab title="Claude Console">
143 <Steps>
144 <Step title="Register the key with Anthropic">
145 In the Claude Console, open **Settings > Encryption keys** and click **Add key**. Enter a display name, choose **Google Cloud KMS**, and click **Continue**. Paste the full key resource name into **Key resource name**, and click **Add**.
146 </Step>
147
148 <Step title="Validate the key">
149 On the **Encryption keys** page, click **Verify** next to the key. **Connected** appears when the check passes. If it fails, a message gives the reason.
150 </Step>
151
152 <Step title="Attach the key to a workspace">
153 Open **Settings > Workspaces**, choose the workspace, and open its **Security** tab. Under **Encryption key**, select the key, click **Save**, and confirm. Attaching a key can't be undone. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
154 </Step>
155 </Steps>
156 </Tab>
157
158 <Tab title="API">
159 <Steps>
160 <Step title="Register the key with Anthropic">
161 Create an external key configuration through the Admin API, using the resource name from the Note the full key resource name step under Encryption key setup.
162
163 <CodeGroup>
164 ```bash cURL
165 curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \
166 -H "x-api-key: $ANTHROPIC_API_KEY" \
167 -H "anthropic-version: 2023-06-01" \
168 -H "content-type: application/json" \
169 -d '{
170 "display_name": "<friendly-name>",
171 "geo": "us",
172 "provider_config": {
173 "type": "gcp",
174 "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
175 }
176 }'
177 ```
178
179 ```bash CLI
180 ant beta:organization:external-keys create <<'YAML'
181 display_name: "<friendly-name>"
182 geo: us
183 provider_config:
184 type: gcp
185 key_name: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
186 YAML
187 ```
188
189 ```python Python
190 client = anthropic.Anthropic()
191
192 external_key = client.beta.organization.external_keys.create(
193 display_name="<friendly-name>",
194 geo="us",
195 provider_config={
196 "type": "gcp",
197 "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",
198 },
199 )
200
201 print(f"id: {external_key.id}")
202 print(f"display_name: {external_key.display_name}")
203 ```
204
205 ```typescript TypeScript
206 const client = new Anthropic();
207
208 const externalKey = await client.beta.organization.externalKeys.create({
209 display_name: "<friendly-name>",
210 geo: "us",
211 provider_config: {
212 type: "gcp",
213 key_name:
214 "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
215 }
216 });
217
218 console.log(`id: ${externalKey.id}`);
219 console.log(`display_name: ${externalKey.display_name}`);
220 ```
221
222 ```csharp C#
223 using Anthropic.Models.Beta.Organization.ExternalKeys;
224
225 AnthropicClient client = new();
226
227 var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()
228 {
229 DisplayName = "<friendly-name>",
230 Geo = Geo.Us,
231 ProviderConfig = new BetaGcpExternalKeyConfig
232 {
233 KeyName = "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
234 }
235 });
236
237 Console.WriteLine($"id: {externalKey.ID}");
238 Console.WriteLine($"display_name: {externalKey.DisplayName}");
239 ```
240
241 ```go Go
242 client := anthropic.NewClient()
243
244 externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{
245 DisplayName: anthropic.String("<friendly-name>"),
246 Geo: anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,
247 ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{
248 OfGCP: &anthropic.BetaGCPExternalKeyConfigParam{
249 KeyName: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",
250 },
251 },
252 })
253 if err != nil {
254 log.Fatal(err)
155255 }
156 }'
157 ```
158
159 ```bash CLI
160 ant beta:organization:external-keys create <<'YAML'
161 display_name: "<friendly-name>"
162 geo: us
163 provider_config:
164 type: gcp
165 key_name: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
166 YAML
167 ```
168
169 ```python Python
170 client = anthropic.Anthropic()
171
172 external_key = client.beta.organization.external_keys.create(
173 display_name="<friendly-name>",
174 geo="us",
175 provider_config={
176 "type": "gcp",
177 "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",
178 },
179 )
180
181 print(f"id: {external_key.id}")
182 print(f"display_name: {external_key.display_name}")
183 ```
184
185 ```typescript TypeScript
186 const client = new Anthropic();
187
188 const externalKey = await client.beta.organization.externalKeys.create({
189 display_name: "<friendly-name>",
190 geo: "us",
191 provider_config: {
192 type: "gcp",
193 key_name:
194 "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
256
257 fmt.Printf("id: %s\n", externalKey.ID)
258 fmt.Printf("display_name: %s\n", externalKey.DisplayName)
259 ```
260
261 ```java Java
262 import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;
263
264 void main() {
265 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
266
267 var params = ExternalKeyCreateParams.builder()
268 .displayName("<friendly-name>")
269 .geo(ExternalKeyCreateParams.Geo.US)
270 .gcpProviderConfig("projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>")
271 .build();
272 var externalKey = client.beta().organization().externalKeys().create(params);
273
274 IO.println("id: " + externalKey.id());
275 IO.println("display_name: " + externalKey.displayName().orElseThrow());
276 }
277 ```
278
279 ```php PHP
280 use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;
281 // ...
282
283 $client = new Client();
284
285 $externalKey = $client->beta->organization->externalKeys->create(
286 displayName: '<friendly-name>',
287 geo: Geo::US,
288 providerConfig: [
289 'type' => 'gcp',
290 'keyName' => 'projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>',
291 ],
292 );
293
294 echo "id: {$externalKey->id}\n";
295 echo "display_name: {$externalKey->displayName}\n";
296 ```
297
298 ```ruby Ruby
299 client = Anthropic::Client.new
300
301 external_key = client.beta.organization.external_keys.create(
302 display_name: "<friendly-name>",
303 geo: :us,
304 provider_config: {
305 type: :gcp,
306 key_name: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
307 }
308 )
309
310 puts "id: #{external_key.id}"
311 puts "display_name: #{external_key.display_name}"
312 ```
313 </CodeGroup>
314
315 The response contains the external key ID:
316
317 ```json
318 {
319 "type": "external_key",
320 "id": "ekey_<id>",
321 "display_name": "<friendly-name>"
195322 }
196 });
197
198 console.log(`id: ${externalKey.id}`);
199 console.log(`display_name: ${externalKey.display_name}`);
200 ```
201
202 ```csharp C#
203 using Anthropic.Models.Beta.Organization.ExternalKeys;
204
205 AnthropicClient client = new();
206
207 var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()
208 {
209 DisplayName = "<friendly-name>",
210 Geo = Geo.Us,
211 ProviderConfig = new BetaGcpExternalKeyConfig
323 ```
324 </Step>
325
326 <Step title="Validate the key">
327 Trigger an encrypt and decrypt round-trip against your key.
328
329 <CodeGroup>
330 ```bash cURL
331 curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \
332 -H "x-api-key: $ANTHROPIC_API_KEY" \
333 -H "anthropic-version: 2023-06-01"
334 ```
335
336 ```bash CLI
337 ant beta:organization:external-keys validate --external-key-id "ekey_<id>"
338 ```
339
340 ```python Python
341 client = anthropic.Anthropic()
342
343 validation = client.beta.organization.external_keys.validate("ekey_<id>")
344
345 print(f"status: {validation.status}")
346 print(f"error: {validation.error}")
347 ```
348
349 ```typescript TypeScript
350 const client = new Anthropic();
351
352 const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");
353
354 console.log(`status: ${validation.status}`);
355 console.log(`error: ${validation.error}`);
356 ```
357
358 ```csharp C#
359 AnthropicClient client = new();
360
361 var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");
362
363 Console.WriteLine($"status: {validation.Status.Raw()}");
364 Console.WriteLine($"error: {validation.Error}");
365 ```
366
367 ```go Go
368 client := anthropic.NewClient()
369
370 validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")
371 if err != nil {
372 log.Fatal(err)
373 }
374
375 fmt.Printf("status: %s\n", validation.Status)
376 fmt.Printf("error: %s\n", validation.Error)
377 ```
378
379 ```java Java
380 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
381
382 var validation = client.beta().organization().externalKeys().validate("ekey_<id>");
383
384 IO.println("status: " + validation.status().asString());
385 IO.println("error: " + validation.error().orElse(""));
386 ```
387
388 ```php PHP
389 $client = new Client();
390
391 $validation = $client->beta->organization->externalKeys->validate(
392 externalKeyID: 'ekey_<id>',
393 );
394
395 echo "status: {$validation->status}\n";
396 echo "error: {$validation->error}\n";
397 ```
398
399 ```ruby Ruby
400 client = Anthropic::Client.new
401
402 external_key_id = "ekey_<id>"
403 validation = client.beta.organization.external_keys.validate(external_key_id)
404
405 puts "status: #{validation.status}"
406 puts "error: #{validation.error}"
407 ```
408 </CodeGroup>
409
410 A successful response looks like this:
411
412 ```json
413 { "type": "external_key_validation", "status": "success", "error": null }
414 ```
415
416 If validation fails, common causes are:
417
418 * **VPC Service Controls:** if a service perimeter protects Cloud KMS in your project, add Anthropic to an access level on the perimeter (or exclude the key's project) so Anthropic can reach the key.
419 * **Domain restricted sharing:** the `constraints/iam.allowedPolicyMemberDomains` org policy can strip the Anthropic service account binding (see the earlier note). Confirm the binding is present with `gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name>`.
420 * **Disabled or destroyed key version:** confirm the key's primary version is enabled, and not disabled, scheduled for destruction, or destroyed.
421 </Step>
422
423 <Step title="Attach the key to a workspace">
424 Once the key is validated, attach it to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
425
426 <CodeGroup>
427 ```bash cURL
428 curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \
429 -H "x-api-key: $ANTHROPIC_API_KEY" \
430 -H "anthropic-version: 2023-06-01" \
431 -H "content-type: application/json" \
432 -d '{
433 "external_key_id": "ekey_<id>"
434 }'
435 ```
436
437 ```bash CLI
438 ant beta:organization:workspaces update \
439 --workspace-id "<workspace-id>" \
440 --external-key-id "ekey_<id>"
441 ```
442
443 ```python Python
444 client = anthropic.Anthropic()
445
446 workspace = client.beta.organization.workspaces.update(
447 "<workspace-id>", external_key_id="ekey_<id>"
448 )
449
450 print(f"id: {workspace.id}")
451 print(f"external_key_id: {workspace.external_key_id}")
452 ```
453
454 ```typescript TypeScript
455 const client = new Anthropic();
456
457 const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {
458 external_key_id: "ekey_<id>"
459 });
460
461 console.log(`id: ${workspace.id}`);
462 console.log(`external_key_id: ${workspace.external_key_id}`);
463 ```
464
465 ```csharp C#
466 AnthropicClient client = new();
467
468 var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()
212469 {
213 KeyName = "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
470 ExternalKeyID = "ekey_<id>"
471 });
472
473 Console.WriteLine($"id: {workspace.ID}");
474 Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");
475 ```
476
477 ```go Go
478 client := anthropic.NewClient()
479
480 workspace, err := client.Beta.Organization.Workspaces.Update(
481 context.Background(),
482 "<workspace-id>",
483 anthropic.BetaOrganizationWorkspaceUpdateParams{
484 ExternalKeyID: anthropic.String("ekey_<id>"),
485 },
486 )
487 if err != nil {
488 log.Fatal(err)
214489 }
215 });
216
217 Console.WriteLine($"id: {externalKey.ID}");
218 Console.WriteLine($"display_name: {externalKey.DisplayName}");
219 ```
220
221 ```go Go
222 client := anthropic.NewClient()
223
224 externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{
225 DisplayName: anthropic.String("<friendly-name>"),
226 Geo: anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,
227 ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{
228 OfGCP: &anthropic.BetaGCPExternalKeyConfigParam{
229 KeyName: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",
230 },
231 },
232 })
233 if err != nil {
234 log.Fatal(err)
235 }
236
237 fmt.Printf("id: %s\n", externalKey.ID)
238 fmt.Printf("display_name: %s\n", externalKey.DisplayName)
239 ```
240
241 ```java Java
242 import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;
243
244 void main() {
245 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
246
247 var params = ExternalKeyCreateParams.builder()
248 .displayName("<friendly-name>")
249 .geo(ExternalKeyCreateParams.Geo.US)
250 .gcpProviderConfig("projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>")
251 .build();
252 var externalKey = client.beta().organization().externalKeys().create(params);
253
254 IO.println("id: " + externalKey.id());
255 IO.println("display_name: " + externalKey.displayName().orElseThrow());
256 }
257 ```
258
259 ```php PHP
260 use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;
261 // ...
262
263 $client = new Client();
264
265 $externalKey = $client->beta->organization->externalKeys->create(
266 displayName: '<friendly-name>',
267 geo: Geo::US,
268 providerConfig: [
269 'type' => 'gcp',
270 'keyName' => 'projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>',
271 ],
272 );
273
274 echo "id: {$externalKey->id}\n";
275 echo "display_name: {$externalKey->displayName}\n";
276 ```
277
278 ```ruby Ruby
279 client = Anthropic::Client.new
280
281 external_key = client.beta.organization.external_keys.create(
282 display_name: "<friendly-name>",
283 geo: :us,
284 provider_config: {
285 type: :gcp,
286 key_name: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
287 }
288 )
289
290 puts "id: #{external_key.id}"
291 puts "display_name: #{external_key.display_name}"
292 ```
293 </CodeGroup>
294
295 The response contains the external key ID:
296
297 ```json
298 {
299 "type": "external_key",
300 "id": "ekey_<id>",
301 "display_name": "<friendly-name>"
302 }
303 ```
304 </Step>
305
306 <Step title="Validate the key">
307 Trigger an encrypt and decrypt round-trip against your key.
308
309 <CodeGroup>
310 ```bash cURL
311 curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \
312 -H "x-api-key: $ANTHROPIC_API_KEY" \
313 -H "anthropic-version: 2023-06-01"
314 ```
315
316 ```bash CLI
317 ant beta:organization:external-keys validate --external-key-id "ekey_<id>"
318 ```
319
320 ```python Python
321 client = anthropic.Anthropic()
322
323 validation = client.beta.organization.external_keys.validate("ekey_<id>")
324
325 print(f"status: {validation.status}")
326 print(f"error: {validation.error}")
327 ```
328
329 ```typescript TypeScript
330 const client = new Anthropic();
331
332 const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");
333
334 console.log(`status: ${validation.status}`);
335 console.log(`error: ${validation.error}`);
336 ```
337
338 ```csharp C#
339 AnthropicClient client = new();
340
341 var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");
342
343 Console.WriteLine($"status: {validation.Status.Raw()}");
344 Console.WriteLine($"error: {validation.Error}");
345 ```
346
347 ```go Go
348 client := anthropic.NewClient()
349
350 validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")
351 if err != nil {
352 log.Fatal(err)
353 }
354
355 fmt.Printf("status: %s\n", validation.Status)
356 fmt.Printf("error: %s\n", validation.Error)
357 ```
358
359 ```java Java
360 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
361
362 var validation = client.beta().organization().externalKeys().validate("ekey_<id>");
363
364 IO.println("status: " + validation.status().asString());
365 IO.println("error: " + validation.error().orElse(""));
366 ```
367
368 ```php PHP
369 $client = new Client();
370
371 $validation = $client->beta->organization->externalKeys->validate(
372 externalKeyID: 'ekey_<id>',
373 );
374
375 echo "status: {$validation->status}\n";
376 echo "error: {$validation->error}\n";
377 ```
378
379 ```ruby Ruby
380 client = Anthropic::Client.new
381
382 external_key_id = "ekey_<id>"
383 validation = client.beta.organization.external_keys.validate(external_key_id)
384
385 puts "status: #{validation.status}"
386 puts "error: #{validation.error}"
387 ```
388 </CodeGroup>
389
390 A successful response looks like this:
391
392 ```json
393 { "type": "external_key_validation", "status": "success", "error": null }
394 ```
395
396 If validation fails, common causes are:
397
398 * **VPC Service Controls:** if a service perimeter protects Cloud KMS in your project, add Anthropic to an access level on the perimeter (or exclude the key's project) so Anthropic can reach the key.
399 * **Domain restricted sharing:** the `constraints/iam.allowedPolicyMemberDomains` org policy can strip the Anthropic service account binding (see the earlier note). Confirm the binding is present with `gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name>`.
400 * **Disabled or destroyed key version:** confirm the key's primary version is enabled, and not disabled, scheduled for destruction, or destroyed.
401 </Step>
402
403 <Step title="Attach the key to a workspace">
404 Once the key is validated, attach it to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).
405
406 <CodeGroup>
407 ```bash cURL
408 curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \
409 -H "x-api-key: $ANTHROPIC_API_KEY" \
410 -H "anthropic-version: 2023-06-01" \
411 -H "content-type: application/json" \
412 -d '{
413 "external_key_id": "ekey_<id>"
414 }'
415 ```
416
417 ```bash CLI
418 ant beta:organization:workspaces update \
419 --workspace-id "<workspace-id>" \
420 --external-key-id "ekey_<id>"
421 ```
422
423 ```python Python
424 client = anthropic.Anthropic()
425
426 workspace = client.beta.organization.workspaces.update(
427 "<workspace-id>", external_key_id="ekey_<id>"
428 )
429
430 print(f"id: {workspace.id}")
431 print(f"external_key_id: {workspace.external_key_id}")
432 ```
433
434 ```typescript TypeScript
435 const client = new Anthropic();
436
437 const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {
438 external_key_id: "ekey_<id>"
439 });
440
441 console.log(`id: ${workspace.id}`);
442 console.log(`external_key_id: ${workspace.external_key_id}`);
443 ```
444
445 ```csharp C#
446 AnthropicClient client = new();
447
448 var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()
449 {
450 ExternalKeyID = "ekey_<id>"
451 });
452
453 Console.WriteLine($"id: {workspace.ID}");
454 Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");
455 ```
456
457 ```go Go
458 client := anthropic.NewClient()
459
460 workspace, err := client.Beta.Organization.Workspaces.Update(
461 context.Background(),
462 "<workspace-id>",
463 anthropic.BetaOrganizationWorkspaceUpdateParams{
464 ExternalKeyID: anthropic.String("ekey_<id>"),
465 },
466 )
467 if err != nil {
468 log.Fatal(err)
469 }
470
471 fmt.Printf("id: %s\n", workspace.ID)
472 fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)
473 ```
474
475 ```java Java
476 import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;
477
478 void main() {
479 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
480
481 var params = WorkspaceUpdateParams.builder()
482 .externalKeyId("ekey_<id>")
483 .build();
484 var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);
485
486 IO.println("id: " + workspace.id());
487 IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());
488 }
489 ```
490
491 ```php PHP
492 $client = new Client();
493
494 $workspace = $client->beta->organization->workspaces->update(
495 workspaceID: '<workspace-id>',
496 externalKeyID: 'ekey_<id>',
497 );
498
499 echo "id: {$workspace->id}\n";
500 echo "external_key_id: {$workspace->externalKeyID}\n";
501 ```
502
503 ```ruby Ruby
504 client = Anthropic::Client.new
505
506 workspace_id = "<workspace-id>"
507 workspace = client.beta.organization.workspaces.update(
508 workspace_id,
509 external_key_id: "ekey_<id>"
510 )
511
512 puts "id: #{workspace.id}"
513 puts "external_key_id: #{workspace.external_key_id}"
514 ```
515 </CodeGroup>
516 </Step>
517 </Steps>
490
491 fmt.Printf("id: %s\n", workspace.ID)
492 fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)
493 ```
494
495 ```java Java
496 import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;
497
498 void main() {
499 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
500
501 var params = WorkspaceUpdateParams.builder()
502 .externalKeyId("ekey_<id>")
503 .build();
504 var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);
505
506 IO.println("id: " + workspace.id());
507 IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());
508 }
509 ```
510
511 ```php PHP
512 $client = new Client();
513
514 $workspace = $client->beta->organization->workspaces->update(
515 workspaceID: '<workspace-id>',
516 externalKeyID: 'ekey_<id>',
517 );
518
519 echo "id: {$workspace->id}\n";
520 echo "external_key_id: {$workspace->externalKeyID}\n";
521 ```
522
523 ```ruby Ruby
524 client = Anthropic::Client.new
525
526 workspace_id = "<workspace-id>"
527 workspace = client.beta.organization.workspaces.update(
528 workspace_id,
529 external_key_id: "ekey_<id>"
530 )
531
532 puts "id: #{workspace.id}"
533 puts "external_key_id: #{workspace.external_key_id}"
534 ```
535 </CodeGroup>
536 </Step>
537 </Steps>
538 </Tab>
539 </Tabs>
518540 </Tab>
519541
520542 <Tab title="Claude Enterprise">
521543
managed-agents/agent-setup Changed · +3 / -3 lines
from line 465
465465
466466The preceding example supplies `version` from the create response, so the update only applies if nothing else has changed the agent since you read it. To apply an update unconditionally, omit `version` from the request:
467467
468<CodeGroup defaultLanguage="cURL">
468<CodeGroup>
469469 ```bash cURL
470470 updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
471471 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 510
510510
511511Fetch the full version history to track how an agent has changed over time. Results are paginated, and the SDK examples fetch every page automatically.
512512
513<CodeGroup defaultLanguage="CLI">
513<CodeGroup>
514514 ```bash cURL
515515 curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
516516 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 576
576576
577577Archiving makes the agent read-only and cannot be undone. Existing sessions continue to run, but new sessions cannot reference the agent. The response sets `archived_at` to the archive timestamp.
578578
579<CodeGroup defaultLanguage="CLI">
579<CodeGroup>
580580 ```bash cURL
581581 archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
582582 -H "x-api-key: $ANTHROPIC_API_KEY" \
managed-agents/budgets Changed · +6 / -9 lines
from line 14
1414
1515Pass the optional `budget` field when you create the session:
1616
17<CodeGroup defaultLanguage="CLI">
17<CodeGroup>
1818 ```bash cURL
19 session=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
19 curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
2020 -H "x-api-key: $ANTHROPIC_API_KEY" \
2121 -H "anthropic-version: 2023-06-01" \
2222 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 31
3131 }
3232 }
3333 EOF
34 )
35 SESSION_ID=$(jq -r '.id' <<< "$session")
3634 ```
3735
3836 ```bash CLI
3937 # Keep the amount quoted so it is sent as a string, not a number.
40 SESSION_ID=$(ant beta:sessions create \
38 ant beta:sessions create \
4139 --agent "$AGENT_ID" \
4240 --environment-id "$ENVIRONMENT_ID" \
43 --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}' \
44 --transform id --raw-output)
41 --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'
4542 ```
4643
4744 ```python Python
from line 191
194191
195192Update the session with a new `max_list_cost`. The new value can be higher or lower than the current cap, but it must be strictly greater than the session's consumed list cost; otherwise the update is rejected with a 400 error: `budget.max_list_cost must be greater than the session's consumed list cost`. Because the consumed cost usually sits [a fraction past the old cap](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget) when the session pauses, base the new value on the session's reported `usage.list_cost`, not on the old `max_list_cost`. Set it a cent or more above that figure: the reported value is rounded and can sit a fraction below the exact consumed cost the check uses.
196193
197<CodeGroup defaultLanguage="CLI">
194<CodeGroup>
198195 ```bash cURL
199196 curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
200197 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 301
304301
305302Set `budget` to `null` to remove the cap entirely. The session's paused work resumes, and the resulting `session.updated` event carries `budget` set to `null`.
306303
307<CodeGroup defaultLanguage="CLI">
304<CodeGroup>
308305 ```bash cURL
309306 curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
310307 -H "x-api-key: $ANTHROPIC_API_KEY" \
managed-agents/define-outcomes Changed · +19 / -25 lines
from line 56
5656
5757<CodeGroup>
5858 ```bash cURL
59 rubric=$(curl -fsSL https://api.anthropic.com/v1/files \
59 curl -fsSL https://api.anthropic.com/v1/files \
6060 -H "x-api-key: $ANTHROPIC_API_KEY" \
6161 -H "anthropic-version: 2023-06-01" \
6262 -H "anthropic-beta: managed-agents-2026-04-01" \
63 -F file=@/tmp/rubric.md)
64 rubric_id=$(jq -r '.id' <<<"$rubric")
65 printf 'Uploaded rubric: %s\n' "$rubric_id"
63 -F file=@/tmp/rubric.md
6664 ```
6765
6866 ```bash CLI
69 RUBRIC_ID=$(ant files upload \
70 --file /tmp/rubric.md \
71 --transform id --raw-output)
67 ant files upload --file /tmp/rubric.md
7268 ```
7369
7470 ```python Python
from line 293
297293 -H "anthropic-beta: managed-agents-2026-04-01" \
298294 --json @- <<EOF
299295 {
300 "agent": "$agent_id",
301 "environment_id": "$environment_id",
296 "agent": "$AGENT_ID",
297 "environment_id": "$ENVIRONMENT_ID",
302298 "title": "Financial analysis on Costco"
303299 }
304300 EOF
305301 )
306 session_id=$(jq -r '.id' <<<"$session")
302 SESSION_ID=$(jq -r '.id' <<<"$session")
307303
308304 # Define the outcome — agent starts working on receipt
309 curl -fsSL "https://api.anthropic.com/v1/sessions/$session_id/events" \
305 curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
310306 -H "x-api-key: $ANTHROPIC_API_KEY" \
311307 -H "anthropic-version: 2023-06-01" \
312308 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 318
322318 ]
323319 }
324320 EOF
325 # or: "rubric": {"type": "file", "file_id": "$rubric_id"}
321 # or: "rubric": {"type": "file", "file_id": "$RUBRIC_ID"}
326322 # "max_iterations" is optional; default 3, max 20
327323 ```
328324
from line 623
627623
628624<CodeGroup>
629625 ```bash cURL
630 session=$(curl -fsSL "https://api.anthropic.com/v1/sessions/$session_id" \
626 curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
631627 -H "x-api-key: $ANTHROPIC_API_KEY" \
632628 -H "anthropic-version: 2023-06-01" \
633 -H "anthropic-beta: managed-agents-2026-04-01")
634
635 jq -r '.outcome_evaluations[] | "\(.outcome_id): \(.result)"' <<<"$session"
636 # outc_01a...: satisfied
629 -H "anthropic-beta: managed-agents-2026-04-01"
637630 ```
638631
639632 ```bash CLI
640 ant beta:sessions retrieve --session-id "$SESSION_ID" \
641 --transform 'outcome_evaluations' --format yaml
633 ant beta:sessions retrieve --session-id "$SESSION_ID"
642634 ```
643635
644636 ```python Python
from line 708
716708 ```bash cURL
717709 # List files produced by this session
718710 # scope_id filtering requires the managed-agents beta
719 files=$(curl -fsSL "https://api.anthropic.com/v1/files?scope_id=$session_id" \
711 curl -fsSL "https://api.anthropic.com/v1/files?scope_id=$SESSION_ID" \
720712 -H "x-api-key: $ANTHROPIC_API_KEY" \
721713 -H "anthropic-version: 2023-06-01" \
722 -H "anthropic-beta: managed-agents-2026-04-01")
723 jq -r '.data[] | "\(.id) \(.filename)"' <<<"$files"
714 -H "anthropic-beta: managed-agents-2026-04-01"
724715
725716 # Download a file
726 file_id=$(jq -r '.data[0].id // empty' <<<"$files")
727 if [[ -n $file_id ]]; then
728 curl -fsSL "https://api.anthropic.com/v1/files/$file_id/content" \
717 FILE_ID=$(curl -fsSL "https://api.anthropic.com/v1/files?scope_id=$SESSION_ID" \
718 -H "x-api-key: $ANTHROPIC_API_KEY" \
719 -H "anthropic-version: 2023-06-01" \
720 -H "anthropic-beta: managed-agents-2026-04-01" | jq -r '.data[0].id // empty')
721 if [[ -n $FILE_ID ]]; then
722 curl -fsSL "https://api.anthropic.com/v1/files/$FILE_ID/content" \
729723 -H "x-api-key: $ANTHROPIC_API_KEY" \
730724 -H "anthropic-version: 2023-06-01" \
731725 -H "anthropic-beta: managed-agents-2026-04-01" \
managed-agents/dreams Changed · +2 / -6 lines
from line 31
3131
3232<CodeGroup>
3333 ```bash cURL
34 dream=$(curl -s https://api.anthropic.com/v1/dreams \
34 curl -s https://api.anthropic.com/v1/dreams \
3535 -H "x-api-key: $ANTHROPIC_API_KEY" \
3636 -H "anthropic-version: 2023-06-01" \
3737 -H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21" \
from line 46
4646 "instructions": "Focus on coding-style preferences; ignore one-off debugging notes."
4747 }
4848 EOF
49 )
50 dream_id=$(jq -r '.id' <<< "$dream")
51 echo "$dream_id" # drm_01...
5249 ```
5350
5451 ```bash CLI
55 dream_id=$(ant beta:dreams create --transform id --raw-output <<YAML
52 ant beta:dreams create <<YAML
5653 inputs:
5754 - type: memory_store
5855 memory_store_id: $store_id
from line 58
6158 model: claude-opus-4-8
6259 instructions: Focus on coding-style preferences; ignore one-off debugging notes.
6360 YAML
64 )
6561 ```
6662
6763 ```python Python
managed-agents/environments Changed · +21 / -27 lines
from line 16
1616
1717<CodeGroup defaultLanguage="CLI">
1818 ```bash cURL
19 environment=$(curl -fsS https://api.anthropic.com/v1/environments \
19 curl -fsS https://api.anthropic.com/v1/environments \
2020 -H "x-api-key: $ANTHROPIC_API_KEY" \
2121 -H "anthropic-version: 2023-06-01" \
2222 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 30
3030 }
3131 }
3232 EOF
33 )
34 environment_id=$(jq -r '.id' <<< "$environment")
35
36 echo "Environment ID: $environment_id"
3733 ```
3834
3935 <MultiFileExample language="cli" label="CLI">
from line 140
144140
145141Pass the environment ID as a string when [creating a session](https://platform.claude.com/docs/en/managed-agents/sessions).
146142
147<CodeGroup defaultLanguage="CLI">
143<CodeGroup>
148144 ```bash cURL
149 session=$(curl -fsS https://api.anthropic.com/v1/sessions \
145 curl -fsS https://api.anthropic.com/v1/sessions \
150146 -H "x-api-key: $ANTHROPIC_API_KEY" \
151147 -H "anthropic-version: 2023-06-01" \
152148 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 149
153149 -H "content-type: application/json" \
154150 --data @- <<EOF
155151 {
156 "agent": "$agent_id",
157 "environment_id": "$environment_id"
152 "agent": "$AGENT_ID",
153 "environment_id": "$ENVIRONMENT_ID"
158154 }
159155 EOF
160 )
161156 ```
162157
163158 ```bash CLI
from line 223
228223
229224<CodeGroup defaultLanguage="CLI">
230225 ```bash cURL
231 environment=$(curl -fsS https://api.anthropic.com/v1/environments \
226 curl -fsS https://api.anthropic.com/v1/environments \
232227 -H "x-api-key: $ANTHROPIC_API_KEY" \
233228 -H "anthropic-version: 2023-06-01" \
234229 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 241
246241 }
247242 }
248243 EOF
249 )
250244 ```
251245
252246 <MultiFileExample language="cli" label="CLI">
from line 575
581575
582576## Manage environments
583577
584<CodeGroup defaultLanguage="CLI">
578<CodeGroup>
585579 ```bash cURL
586580 # List environments
587 environments=$(curl -fsS https://api.anthropic.com/v1/environments \
581 curl -fsS https://api.anthropic.com/v1/environments \
588582 -H "x-api-key: $ANTHROPIC_API_KEY" \
589583 -H "anthropic-version: 2023-06-01" \
590 -H "anthropic-beta: managed-agents-2026-04-01")
584 -H "anthropic-beta: managed-agents-2026-04-01"
591585
592586 # Retrieve a specific environment
593 env=$(curl -fsS "https://api.anthropic.com/v1/environments/$environment_id" \
587 curl -fsS "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID" \
594588 -H "x-api-key: $ANTHROPIC_API_KEY" \
595589 -H "anthropic-version: 2023-06-01" \
596 -H "anthropic-beta: managed-agents-2026-04-01")
590 -H "anthropic-beta: managed-agents-2026-04-01"
597591
598592 # Archive an environment (read-only, existing sessions continue)
599 curl -fsS -X POST "https://api.anthropic.com/v1/environments/$environment_id/archive" \
593 curl -fsS -X POST "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive" \
600594 -H "x-api-key: $ANTHROPIC_API_KEY" \
601595 -H "anthropic-version: 2023-06-01" \
602596 -H "anthropic-beta: managed-agents-2026-04-01"
603597
604598 # Delete an environment (only if no sessions reference it)
605 curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$environment_id" \
599 curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID" \
606600 -H "x-api-key: $ANTHROPIC_API_KEY" \
607601 -H "anthropic-version: 2023-06-01" \
608602 -H "anthropic-beta: managed-agents-2026-04-01"
managed-agents/events-and-streaming Changed · +7 / -10 lines
from line 920
920920 -H "x-api-key: $ANTHROPIC_API_KEY" \
921921 -H "anthropic-version: 2023-06-01" \
922922 -H "anthropic-beta: managed-agents-2026-04-01" \
923 -H "content-type: application/json" \
924 | jq -r '.data[] | "[\(.type)] \(.processed_at)"'
923 -H "content-type: application/json"
925924 ```
926925
927926 ```bash CLI
928 ant beta:sessions:events list --session-id "$SESSION_ID" \
929 --format jsonl --transform '{type,processed_at}'
927 ant beta:sessions:events list --session-id "$SESSION_ID" --format jsonl
930928 ```
931929
932930 ```python Python
from line 989
991989 curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true&types[]=agent.tool_use&types[]=agent.tool_result" \
992990 -H "x-api-key: $ANTHROPIC_API_KEY" \
993991 -H "anthropic-version: 2023-06-01" \
994 -H "anthropic-beta: managed-agents-2026-04-01" \
995 | jq -r '.data[] | "[\(.type)] \(.processed_at)"'
992 -H "anthropic-beta: managed-agents-2026-04-01"
996993 ```
997994
998995 ```bash CLI
999996 ant beta:sessions:events list --session-id "$SESSION_ID" \
1000997 --type agent.tool_use --type agent.tool_result \
1001 --format jsonl --transform '{type,processed_at}'
998 --format jsonl
1002999 ```
10031000
10041001 ```python Python
from line 1582
15851582
15861583The preview events themselves don't change. `event_start` and `event_delta` have the same shape on a thread stream as on the session-level stream, and the [accumulate and reconcile](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#accumulate-and-reconcile) pattern applies as written. The one adjustment is bookkeeping: run one accumulator instance per stream connection.
15871584
1588<CodeGroup defaultLanguage="cURL">
1585<CodeGroup>
15891586 ```bash cURL
15901587 # List the session's threads and pick a child: child threads carry a non-null
15911588 # parent_thread_id, and the primary thread's parent_thread_id is null.
from line 2456
24592456
24602457To resume a session, send a `user.message` event to it as usual:
24612458
2462<CodeGroup defaultLanguage="CLI">
2459<CodeGroup>
24632460 ```bash cURL
24642461 # In production, pass the stored ID of the session you want to resume.
24652462 curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
from line 2640
26432640
26442641Send a `system.message` event to give the agent privileged system-level context that applies to the accompanying turn and all subsequent turns. Unlike the `system` field on the agent definition (which sets the top-level system prompt), `system.message` content is appended to the session's system context as a `role: "system"` turn rather than replacing that prompt. Use it when the agent needs updated system-level guidance mid-session: a different persona, revised constraints, or context fetched at runtime that should shape the model's behavior going forward.
26452642
2646<CodeGroup defaultLanguage="CLI">
2643<CodeGroup>
26472644 ```bash cURL
26482645 curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
26492646 -H "x-api-key: $ANTHROPIC_API_KEY" \
managed-agents/files Changed · +25 / -37 lines
from line 19
1919 file=$(curl --fail-with-body -sS "${auth[@]}" \
2020 "${base_url}/files" \
22 file_id=$(jq -er '.id' <<<"${file}")
23 printf 'File ID: %s\n' "${file_id}"
22 FILE_ID=$(jq -er '.id' <<<"${file}")
2423 ```
2524
2625 ```bash CLI
from line 90
9190
9291<CodeGroup>
9392 ```bash cURL
94 session=$(
95 jq -n \
96 --arg agent_id "${agent_id}" \
97 --arg environment_id "${environment_id}" \
98 --arg file_id "${file_id}" \
99 '{
100 agent: $agent_id,
101 environment_id: $environment_id,
102 resources: [
103 {
104 type: "file",
105 file_id: $file_id,
106 mount_path: "/data.csv"
107 }
108 ]
109 }' | curl --fail-with-body -sS "${auth[@]}" "${base_url}/sessions" --json @-
110 )
111 session_id=$(jq -er '.id' <<<"${session}")
93 jq -n \
94 --arg agent_id "${AGENT_ID}" \
95 --arg environment_id "${ENVIRONMENT_ID}" \
96 --arg file_id "${FILE_ID}" \
97 '{
98 agent: $agent_id,
99 environment_id: $environment_id,
100 resources: [
101 {
102 type: "file",
103 file_id: $file_id,
104 mount_path: "/data.csv"
105 }
106 ]
107 }' | curl --fail-with-body -sS "${auth[@]}" "${base_url}/sessions" --json @-
112108 ```
113109
114110 ```bash CLI
115 SESSION_ID=$(ant beta:sessions create \
111 ant beta:sessions create \
116112 --agent "$AGENT_ID" \
117 --environment-id "$ENVIRONMENT_ID" \
118 --transform id --raw-output <<EOF
113 --environment-id "$ENVIRONMENT_ID" <<EOF
119114 resources:
120115 - type: file
121116 file_id: $FILE_ID
122117 mount_path: /data.csv
123118 EOF
124 )
125119 ```
126120
127121 ```python Python
from line 362
368362
369363<CodeGroup>
370364 ```bash cURL
371 resource=$(
372 jq -n --arg file_id "${file_id}" '{type: "file", file_id: $file_id}' \
373 | curl --fail-with-body -sS "${auth[@]}" \
374 "${base_url}/sessions/${session_id}/resources" --json @-
375 )
376 resource_id=$(jq -er '.id' <<<"${resource}")
377 printf '%s\n' "${resource_id}" # "sesrsc_01ABC..."
365 jq -n --arg file_id "${FILE_ID}" '{type: "file", file_id: $file_id}' \
366 | curl --fail-with-body -sS "${auth[@]}" \
367 "${base_url}/sessions/${SESSION_ID}/resources" --json @-
378368 ```
379369
380370 ```bash CLI
381 RESOURCE_ID=$(ant beta:sessions:resources add \
371 ant beta:sessions:resources add \
382372 --session-id "$SESSION_ID" \
383373 --type file \
384 --file-id "$FILE_ID" \
385 --transform id --raw-output)
374 --file-id "$FILE_ID"
386375 ```
387376
388377 ```python Python
from line 455
466455<CodeGroup>
467456 ```bash cURL
468457 curl --fail-with-body -sS "${auth[@]}" \
469 "${base_url}/sessions/${session_id}/resources" \
470 | jq -r '.data[] | "\(.id) \(.type)"'
458 "${base_url}/sessions/${SESSION_ID}/resources"
471459
472460 curl --fail-with-body -sS "${auth[@]}" -X DELETE \
473 "${base_url}/sessions/${session_id}/resources/${resource_id}" >/dev/null
461 "${base_url}/sessions/${SESSION_ID}/resources/${RESOURCE_ID}" >/dev/null
474462 ```
475463
476464 ```bash CLI
managed-agents/memory Changed · +29 / -42 lines
from line 28
2828
2929Give the store a `name` and a `description`. The description is passed to the agent, telling it what the store contains.
3030
31<CodeGroup defaultLanguage="CLI">
31<CodeGroup>
3232 ```bash cURL
33 store=$(curl -s https://api.anthropic.com/v1/memory_stores \
33 curl -s https://api.anthropic.com/v1/memory_stores \
3434 -H "x-api-key: $ANTHROPIC_API_KEY" \
3535 -H "anthropic-version: 2023-06-01" \
3636 -H "anthropic-beta: agent-memory-2026-07-22" \
3737 -H "content-type: application/json" \
38 -d '{"name": "User Preferences", "description": "Per-user preferences and project context."}')
39 store_id=$(jq -r '.id' <<< "$store")
40 echo "$store_id" # memstore_01Hx...
38 -d '{"name": "User Preferences", "description": "Per-user preferences and project context."}'
4139 ```
4240
4341 ```bash CLI
44 store_id=$(ant beta:memory-stores create \
42 ant beta:memory-stores create \
4543 --name "User Preferences" \
46 --description "Per-user preferences and project context." \
47 --transform id --raw-output)
44 --description "Per-user preferences and project context."
4845 ```
4946
5047 ```python Python
from line 121
124121
125122Pre-load a store with reference material before any agent runs:
126123
127<CodeGroup defaultLanguage="CLI">
124<CodeGroup>
128125 ```bash cURL
129126 curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
130127 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 211
214211
215212You can configure `access` as well. It defaults to `read_write` (shown explicitly in the following example), but `read_only` is also supported.
216213
217<CodeGroup defaultLanguage="CLI">
214<CodeGroup>
218215 ```bash cURL
219216 curl -s https://api.anthropic.com/v1/sessions \
220217 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 397
400397* `path_prefix` scopes the list to one directory. It must end with `/` and matches whole path segments, so `path_prefix=/notes/` returns `/notes/todo.md` but not `/notes-archive/todo.md`.
401398* `depth` controls how deep the listing goes below `path_prefix`: omit it (or pass `0`) to list the whole subtree, or pass `1` to list only the immediate children. Other values return a `400` error.
402399
403<CodeGroup defaultLanguage="CLI">
400<CodeGroup>
404401 ```bash cURL
405402 curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memories?path_prefix=/" \
406403 -H "x-api-key: $ANTHROPIC_API_KEY" \
407404 -H "anthropic-version: 2023-06-01" \
408 -H "anthropic-beta: agent-memory-2026-07-22" | jq -r '.data[] | "\(.type) \(.path)"'
405 -H "anthropic-beta: agent-memory-2026-07-22"
409406 ```
410407
411408 ```bash CLI
from line 493
496493
497494Fetching an individual memory returns the full content.
498495
499<CodeGroup defaultLanguage="CLI">
496<CodeGroup>
500497 ```bash cURL
501498 curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
502499 -H "x-api-key: $ANTHROPIC_API_KEY" \
503500 -H "anthropic-version: 2023-06-01" \
504 -H "anthropic-beta: agent-memory-2026-07-22" | jq -r '.content'
501 -H "anthropic-beta: agent-memory-2026-07-22"
505502 ```
506503
507504 ```bash CLI
from line 568
571568
572569`memories.create` creates a memory at a given `path`. Create does not overwrite; to change an existing memory, use [`memories.update`](https://platform.claude.com/docs/en/managed-agents/memory#update-a-memory).
573570
574<CodeGroup defaultLanguage="CLI">
571<CodeGroup>
575572 ```bash cURL
576 mem=$(curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
573 curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
577574 -H "x-api-key: $ANTHROPIC_API_KEY" \
578575 -H "anthropic-version: 2023-06-01" \
579576 -H "anthropic-beta: agent-memory-2026-07-22" \
580577 -H "content-type: application/json" \
581 -d '{"path": "/preferences/formatting.md", "content": "Always use tabs, not spaces."}')
582 mem_id=$(jq -r '.id' <<< "$mem")
583 mem_sha=$(jq -r '.content_sha256' <<< "$mem")
578 -d '{"path": "/preferences/formatting.md", "content": "Always use tabs, not spaces."}'
584579 ```
585580
586581 ```bash CLI
587 mem=$(ant beta:memory-stores:memories create \
582 ant beta:memory-stores:memories create \
588583 --memory-store-id "$store_id" \
589584 --path "/preferences/formatting.md" \
590 --content "Always use tabs, not spaces." \
591 --format json)
592 mem_id=$(jq -r '.id' <<< "$mem")
593 mem_sha=$(jq -r '.content_sha256' <<< "$mem")
585 --content "Always use tabs, not spaces."
594586 ```
595587
596588 ```python Python
from line 651
659651
660652`memories.update` modifies an existing memory by ID. You can change `content`, `path` (a rename), or both. The example renames a memory to an archive path:
661653
662<CodeGroup defaultLanguage="CLI">
654<CodeGroup>
663655 ```bash cURL
664656 curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
665657 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 735
743735
744736To avoid clobbering a concurrent write, pass a `content_sha256` precondition. The update only applies if the stored content hash still matches the one you read; on mismatch, re-read the memory and retry against the fresh state.
745737
746<CodeGroup defaultLanguage="CLI">
738<CodeGroup>
747739 ```bash cURL
748740 curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
749741 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 840
848840
849841### Delete a memory
850842
851<CodeGroup defaultLanguage="CLI">
843<CodeGroup>
852844 ```bash cURL
853845 curl -s -X DELETE "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
854846 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 919
927919
928920List version history for a store, newest first. The example filters to a single memory's history:
929921
930<CodeGroup defaultLanguage="CLI">
922<CodeGroup>
931923 ```bash cURL
932 versions=$(curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions?memory_id=$mem_id" \
924 curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions?memory_id=$mem_id" \
933925 -H "x-api-key: $ANTHROPIC_API_KEY" \
934926 -H "anthropic-version: 2023-06-01" \
935 -H "anthropic-beta: agent-memory-2026-07-22")
936 jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
937 version_id=$(jq -r '.data[1].id' <<< "$versions")
927 -H "anthropic-beta: agent-memory-2026-07-22"
938928 ```
939929
940930 ```bash CLI
941 versions=$(ant beta:memory-stores:memory-versions list \
931 ant beta:memory-stores:memory-versions list \
942932 --memory-store-id "$store_id" \
943933 --memory-id "$mem_id" \
944 --format json)
945 # `list --format json` emits one JSON object per item.
946 jq -r '"\(.id): \(.operation)"' <<< "$versions"
947 version_id=$(jq -rs '.[1].id' <<< "$versions")
934 --format json
948935 ```
949936
950937 ```python Python
from line 1035
10481035
10491036Fetching an individual version returns the same fields as the list response plus the full `content` body.
10501037
1051<CodeGroup defaultLanguage="CLI">
1038<CodeGroup>
10521039 ```bash cURL
10531040 curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions/$version_id" \
10541041 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 1115
11281115
11291116A version that is the current head of a live memory cannot be redacted. Write a new version first (or delete the memory), then redact the old one.
11301117
1131<CodeGroup defaultLanguage="CLI">
1118<CodeGroup>
11321119 ```bash cURL
11331120 curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions/$version_id/redact" \
11341121 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 1192
12051192
12061193List stores in the workspace. Archived stores are excluded by default; pass `include_archived: true` to include them.
12071194
1208<CodeGroup defaultLanguage="CLI">
1195<CodeGroup>
12091196 ```bash cURL
12101197 curl -s "https://api.anthropic.com/v1/memory_stores?include_archived=true" \
12111198 -H "x-api-key: $ANTHROPIC_API_KEY" \
12121199 -H "anthropic-version: 2023-06-01" \
1213 -H "anthropic-beta: agent-memory-2026-07-22" | jq '.data[] | {id, name, archived_at}'
1200 -H "anthropic-beta: agent-memory-2026-07-22"
12141201 ```
12151202
12161203 ```bash CLI
from line 1265
12781265
12791266Archiving makes a store read-only and prevents it from being attached to new sessions. Archiving is one-way; there is no unarchive.
12801267
1281<CodeGroup defaultLanguage="CLI">
1268<CodeGroup>
12821269 ```bash cURL
12831270 curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/archive" \
12841271 -H "x-api-key: $ANTHROPIC_API_KEY" \
managed-agents/multiagent-orchestration Changed · +91 / -69 lines
from line 415
415415
416416[Agent configuration overrides](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session) at session creation can replace the coordinator's MCP servers and those of its `self` copies.
417417
418<CodeGroup>
418Create the researcher, which declares the GitHub MCP server, and the coordinator that delegates to the researcher:
419
420<CodeGroup defaultLanguage="CLI">
419421 ```bash cURL
420422 research_agent_id=$(curl --fail-with-body -sS "$BASE/v1/agents" "${H[@]}" --data @- <<'EOF' | jq -er '.id'
421423 {
from line 441
439441 }
440442 EOF
441443 )
442
443 session_id=$(curl --fail-with-body -sS "$BASE/v1/sessions" "${H[@]}" --data @- <<EOF | jq -er '.id'
444 {
445 "agent": "$coordinator_id",
446 "environment_id": "$environment_id",
447 "vault_ids": ["$vault_id"]
448 }
449 EOF
450 )
451 echo "$session_id"
452444 ```
453445
454446 <MultiFileExample language="cli" label="CLI">
from line 478
486478 ---
487479 ```
488480 </File>
489
490 ```bash CLI
491 session_id=$(ant beta:sessions create \
492 --agent "$coordinator_id" \
493 --environment-id "$environment_id" \
494 --vault-id "$vault_id" \
495 --transform id --raw-output)
496 echo "$session_id"
497 ```
498481 </MultiFileExample>
499482
500483 ```python Python
from line 499
516499 "agents": [{"type": "agent", "id": research_agent.id}],
517500 },
518501 )
519
520 session = client.beta.sessions.create(
521 agent=coordinator.id,
522 environment_id=environment.id,
523 vault_ids=[vault.id],
524 )
525 print(session.id)
526502 ```
527503
528504 ```typescript TypeScript
from line 520
544520 agents: [{ type: "agent", id: researchAgent.id }],
545521 },
546522 });
547
548 const session = await client.beta.sessions.create({
549 agent: coordinator.id,
550 environment_id: environment.id,
551 vault_ids: [vault.id],
552 });
553 console.log(session.id);
554523 ```
555524
556525 ```csharp C#
from line 570
601570 ],
602571 },
603572 });
604
605 var session = await client.Beta.Sessions.Create(new()
606 {
607 Agent = coordinator.ID,
608 EnvironmentID = environment.ID,
609 VaultIds = [vault.ID],
610 });
611 Console.WriteLine(session.ID);
612573 ```
613574
614575 ```go Go
from line 613
652613 if err != nil {
653614 panic(err)
654615 }
655
656 session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
657 Agent: anthropic.BetaSessionNewParamsAgentUnion{
658 OfString: anthropic.String(coordinator.ID),
659 },
660 EnvironmentID: environment.ID,
661 VaultIDs: []string{vault.ID},
662 })
663 if err != nil {
664 panic(err)
665 }
666 fmt.Println(session.ID)
667616 ```
668617
669618 ```java Java
from line 648
699648 .build())
700649 .build()
701650 );
702
703 var session = client.beta().sessions().create(SessionCreateParams.builder()
704 .agent(coordinator.id())
705 .environmentId(environment.id())
706 .vaultIds(List.of(vault.id()))
707 .build());
708 IO.println(session.id());
709651 ```
710652
711653 ```php PHP
from line 675
733675 ],
734676 ],
735677 );
736
737 $session = $client->beta->sessions->create(
738 agent: $coordinator->id,
739 environmentID: $environment->id,
740 vaultIDs: [$vault->id],
741 );
742 echo "{$session->id}\n";
743678 ```
744679
745680 ```ruby Ruby
from line 702
767702 ]
768703 }
769704 )
705 ```
706</CodeGroup>
770707
708Then create the session with the vault that holds the GitHub credential:
709
710<CodeGroup>
711 ```bash cURL
712 session_id=$(curl --fail-with-body -sS "$BASE/v1/sessions" "${H[@]}" --data @- <<EOF | jq -er '.id'
713 {
714 "agent": "$coordinator_id",
715 "environment_id": "$environment_id",
716 "vault_ids": ["$vault_id"]
717 }
718 EOF
719 )
720 echo "$session_id"
721 ```
722
723 ```bash CLI
724 session_id=$(ant beta:sessions create \
725 --agent "$coordinator_id" \
726 --environment-id "$environment_id" \
727 --vault-id "$vault_id" \
728 --transform id --raw-output)
729 echo "$session_id"
730 ```
731
732 ```python Python
733 session = client.beta.sessions.create(
734 agent=coordinator.id,
735 environment_id=environment.id,
736 vault_ids=[vault.id],
737 )
738 print(session.id)
739 ```
740
741 ```typescript TypeScript
742 const session = await client.beta.sessions.create({
743 agent: coordinator.id,
744 environment_id: environment.id,
745 vault_ids: [vault.id],
746 });
747 console.log(session.id);
748 ```
749
750 ```csharp C#
751 var session = await client.Beta.Sessions.Create(new()
752 {
753 Agent = coordinator.ID,
754 EnvironmentID = environment.ID,
755 VaultIds = [vault.ID],
756 });
757 Console.WriteLine(session.ID);
758 ```
759
760 ```go Go
761 session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
762 Agent: anthropic.BetaSessionNewParamsAgentUnion{
763 OfString: anthropic.String(coordinator.ID),
764 },
765 EnvironmentID: environment.ID,
766 VaultIDs: []string{vault.ID},
767 })
768 if err != nil {
769 panic(err)
770 }
771 fmt.Println(session.ID)
772 ```
773
774 ```java Java
775 var session = client.beta().sessions().create(SessionCreateParams.builder()
776 .agent(coordinator.id())
777 .environmentId(environment.id())
778 .vaultIds(List.of(vault.id()))
779 .build());
780 IO.println(session.id());
781 ```
782
783 ```php PHP
784 $session = $client->beta->sessions->create(
785 agent: $coordinator->id,
786 environmentID: $environment->id,
787 vaultIDs: [$vault->id],
788 );
789 echo "{$session->id}\n";
790 ```
791
792 ```ruby Ruby
771793 session = client.beta.sessions.create(
772794 agent: coordinator.id,
773795 environment_id: environment.id,
managed-agents/onboarding Changed · +3 / -3 lines
from line 32
32321. Copy the agent ID and [environment ID](https://platform.claude.com/docs/en/managed-agents/environments) from Console.
33332. Reference them in your code when [creating sessions](https://platform.claude.com/docs/en/managed-agents/sessions):
3434
35<CodeGroup defaultLanguage="CLI">
35<CodeGroup>
3636 ```bash cURL
37 session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
37 curl -fsSL https://api.anthropic.com/v1/sessions \
3838 -H "x-api-key: $ANTHROPIC_API_KEY" \
3939 -H "anthropic-version: 2023-06-01" \
4040 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 43
4343 "agent": "agent_01J8XkN5uT3vHpLqRfWdY2",
4444 "environment_id": "env_01K2mPsT7hNwR4jXuLvCqD8",
4545 "title": "My first session"
46 }')
46 }'
4747 ```
4848
4949 ```bash CLI
managed-agents/scheduled-deployments Changed · +14 / -17 lines
from line 20
2020* Deployments also require at least one initial event, a `user.message` or `user.define_outcome`, that starts each session's work.
2121* In the `schedule`, you define a cron `expression` and a `timezone`. Maximum granularity supported is at the minute level.
2222
23<CodeGroup defaultLanguage="CLI">
23<CodeGroup>
2424 ```bash cURL
25 DEPLOYMENT_ID=$(
26 curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments?beta=true" \
27 -H "x-api-key: $ANTHROPIC_API_KEY" \
28 -H "anthropic-version: 2023-06-01" \
29 -H "anthropic-beta: managed-agents-2026-04-01" \
30 -H "content-type: application/json" \
31 -d @- <<EOF | jq -er '.id'
25 curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments?beta=true" \
26 -H "x-api-key: $ANTHROPIC_API_KEY" \
27 -H "anthropic-version: 2023-06-01" \
28 -H "anthropic-beta: managed-agents-2026-04-01" \
29 -H "content-type: application/json" \
30 -d @- <<EOF
3231 {
3332 "name": "Weekly compliance scan",
3433 "agent": "$AGENT_ID",
from line 42
4342 }
4443 }
4544 EOF
46 )
4745 ```
4846
4947 ```bash CLI
50 DEPLOYMENT_ID=$(ant beta:deployments create <<YAML | jq -er '.id'
48 ant beta:deployments create <<YAML
5149 name: Weekly compliance scan
5250 agent: $AGENT_ID
5351 environment_id: $ENVIRONMENT_ID
from line 59
6159 expression: "0 20 * * 5"
6260 timezone: America/New_York
6361 YAML
64 )
6562 ```
6663
6764 ```python Python
from line 287
290287
291288List all deployment runs for a deployment as follows:
292289
293<CodeGroup defaultLanguage="CLI">
290<CodeGroup>
294291 ```bash cURL
295292 curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID" \
296293 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 376
379376
380377You can additionally filter on deployment runs with errors:
381378
382<CodeGroup defaultLanguage="CLI">
379<CodeGroup>
383380 ```bash cURL
384381 curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID&has_error=true" \
385382 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 486
489486
490487**Pause** suppresses scheduled triggers on a go-forward basis; running sessions from a prior deployment run continue to execute. Manual runs through the `run` endpoint are still allowed while paused. Pausing sets `paused_reason` to `{"type": "manual"}`; unpausing clears it.
491488
492<CodeGroup defaultLanguage="CLI">
489<CodeGroup>
493490 ```bash cURL
494491 curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/pause?beta=true" \
495492 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 531
534531
535532**Unpause** resumes the schedule from the next scheduled occurrence. Missed triggers are not backfilled.
536533
537<CodeGroup defaultLanguage="CLI">
534<CodeGroup>
538535 ```bash cURL
539536 curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/unpause?beta=true" \
540537 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 576
579576
580577**Archive**, unlike **pause**, is terminal: the schedule terminates and the deployment cannot be modified.
581578
582<CodeGroup defaultLanguage="CLI">
579<CodeGroup>
583580 ```bash cURL
584581 curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/archive?beta=true" \
585582 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 629
632629
633630To run a deployment outside its schedule, call the [`run` endpoint](https://platform.claude.com/docs/en/api/beta/deployments/run). This creates a session immediately and writes a deployment run with `trigger_context.type: "manual"`. This allows you to test a deployment before committing to the schedule.
634631
635<CodeGroup defaultLanguage="CLI">
632<CodeGroup>
636633 ```bash cURL
637634 curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/run?beta=true" \
638635 -H "x-api-key: $ANTHROPIC_API_KEY" \
managed-agents/session-operations Changed · +7 / -8 lines
from line 31
3131
3232The session must be `idle` to update the agent. To update the agent while the session is running, send a [`user.interrupt` event](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#integrating-events) by itself and wait for the session to become `idle`.
3333
34<CodeGroup defaultLanguage="CLI">
34<CodeGroup>
3535 ```bash cURL
3636 curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
3737 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 217
217217
218218## Retrieving a session
219219
220<CodeGroup defaultLanguage="CLI">
220<CodeGroup>
221221 ```bash cURL
222 retrieved=$(curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
222 curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
223223 -H "x-api-key: $ANTHROPIC_API_KEY" \
224224 -H "anthropic-version: 2023-06-01" \
225 -H "anthropic-beta: managed-agents-2026-04-01")
226 echo "Status: $(jq -r '.status' <<< "$retrieved")"
225 -H "anthropic-beta: managed-agents-2026-04-01"
227226 ```
228227
229228 ```bash CLI
from line 276
277276
278277A `page` cursor is opaque and encodes the `order` of the request that produced it. The `order` query parameter sets the sort direction of the results, `asc` or `desc` by creation time; the default is `desc` (newest first). Reusing a cursor with a different `order` returns a 400 error, as does changing a `created_at` filter so that it excludes the cursor's position. Other query parameters, including the remaining filters and `limit`, can change between paginated requests. For the pagination fields shared across list endpoints, see [Pagination](https://platform.claude.com/docs/en/api/overview#pagination).
279278
280<CodeGroup defaultLanguage="CLI">
279<CodeGroup>
281280 ```bash cURL
282281 first_page=$(curl -sS --fail-with-body \
283282 "https://api.anthropic.com/v1/sessions?agent_id=$AGENT_ID&limit=1" \
from line 533
534533
535534Archive a session to prevent new events from being sent while preserving its history. A `running` session cannot be archived; to archive one, send a [`user.interrupt` event](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#integrating-events) by itself and wait for the session to become `idle`.
536535
537<CodeGroup defaultLanguage="CLI">
536<CodeGroup>
538537 ```bash cURL
539538 curl -fsSL -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/archive" \
540539 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 584
585584
586585Memory stores, vaults, skills, environments, and agents are independent resources and are not affected by session deletion. Files you uploaded through the Files API are also unaffected, but files the session itself produced are scoped to it and are permanently deleted along with its filesystem. Download anything you need to keep before deleting the session. An output file written at the end of the last turn can take a few seconds after the session goes idle to appear in the [session's file list](https://platform.claude.com/docs/en/managed-agents/files#listing-and-downloading-session-files), so check that the files you expect are listed first.
587586
588<CodeGroup defaultLanguage="CLI">
587<CodeGroup>
589588 ```bash cURL
590589 curl -fsSL -X DELETE "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
591590 -H "x-api-key: $ANTHROPIC_API_KEY" \
managed-agents/sessions Changed · +12 / -23 lines
from line 14
1414
1515A session requires an `agent` ID and an `environment` ID. Agents are versioned resources; passing in the `agent` ID as a string creates the session with the latest agent version.
1616
17<CodeGroup defaultLanguage="CLI">
17<CodeGroup>
1818 ```bash cURL
19 session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
19 curl -fsSL https://api.anthropic.com/v1/sessions \
2020 -H "x-api-key: $ANTHROPIC_API_KEY" \
2121 -H "anthropic-version: 2023-06-01" \
2222 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 27
2727 "environment_id": "$ENVIRONMENT_ID"
2828 }
2929 EOF
30 )
31 SESSION_ID=$(jq -r '.id' <<< "$session")
3230 ```
3331
3432 ```bash CLI
from line 93
9593
9694To pin a session to a specific agent version, pass an object. This lets you control exactly which version runs and stage rollouts of new versions independently.
9795
98<CodeGroup defaultLanguage="CLI">
96<CodeGroup>
9997 ```bash cURL
100 pinned_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
98 curl -fsSL https://api.anthropic.com/v1/sessions \
10199 -H "x-api-key: $ANTHROPIC_API_KEY" \
102100 -H "anthropic-version: 2023-06-01" \
103101 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 106
108106 "environment_id": "$ENVIRONMENT_ID"
109107 }
110108 EOF
111 )
112 PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")
113109 ```
114110
115111 ```bash CLI
from line 193
197193
198194The following example creates a session with a single `user.message` in `initial_events`:
199195
200<CodeGroup defaultLanguage="CLI">
196<CodeGroup>
201197 ```bash cURL
202198 seeded_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
203199 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 477
481477
482478The following example starts a session that overrides the model and clears the system prompt:
483479
484<CodeGroup defaultLanguage="CLI">
480<CodeGroup>
485481 ```bash cURL
486 override_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
482 curl -fsSL https://api.anthropic.com/v1/sessions \
487483 -H "x-api-key: $ANTHROPIC_API_KEY" \
488484 -H "anthropic-version: 2023-06-01" \
489485 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 495
499495 "environment_id": "$ENVIRONMENT_ID"
500496 }
501497 EOF
502 )
503 jq '.agent | {id, version, model, system}' <<< "$override_session"
504 OVERRIDE_SESSION_ID=$(jq -r '.id' <<< "$override_session")
505498 ```
506499
507500 ```bash CLI
508501 # The response's `agent` is the resolved snapshot: each override replaces that
509502 # field for this session only, and the agent resource keeps its id and version.
510 ant beta:sessions create \
511 --transform 'agent.{id,version,model,system}' \
512 --format json <<YAML
503 ant beta:sessions create <<YAML
513504 agent:
514505 type: agent_with_overrides
515506 id: $AGENT_ID
from line 644
653644
654645The following example starts a session from an agent whose model has no geo pin, pins the session's model requests to US inference by including `inference_geo` in the `model` override, and prints the value echoed in the response's `agent.model`:
655646
656<CodeGroup defaultLanguage="CLI">
647<CodeGroup>
657648 ```bash cURL
658649 # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.
659650 session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
from line 827
836827
837828If your agent uses MCP tools that require authentication, pass `vault_ids` at session creation to reference a vault containing stored OAuth credentials. Anthropic manages token refresh on your behalf. See [Authenticate with vaults](https://platform.claude.com/docs/en/managed-agents/vaults) for how to create vaults and register credentials.
838829
839<CodeGroup defaultLanguage="CLI">
830<CodeGroup>
840831 ```bash cURL
841 vault_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
832 curl -fsSL https://api.anthropic.com/v1/sessions \
842833 -H "x-api-key: $ANTHROPIC_API_KEY" \
843834 -H "anthropic-version: 2023-06-01" \
844835 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 841
850841 "vault_ids": ["$VAULT_ID"]
851842 }
852843 EOF
853 )
854 VAULT_SESSION_ID=$(jq -r '.id' <<< "$vault_session")
855844 ```
856845
857846 ```bash CLI
from line 919
930919
931920Creating a session without `initial_events` registers the session but does not start any work; the environment's sandbox begins provisioning as soon as the session is created, so the first tool call does not wait on it. To delegate a task, send events to the session using a [user event](https://platform.claude.com/docs/en/managed-agents/reference#event-types). To supply the first event in the create request instead, see [Seed the session with initial events](https://platform.claude.com/docs/en/managed-agents/sessions#seed-the-session-with-initial-events). The session acts as a state machine that tracks progress while events drive the actual execution.
932921
933<CodeGroup defaultLanguage="CLI">
922<CodeGroup>
934923 ```bash cURL
935924 curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
936925 -H "x-api-key: $ANTHROPIC_API_KEY" \
managed-agents/vaults Changed · +28 / -39 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
agents-and-tools/agent-skills/quickstart Changed · +1 / -1 lines
from line 29
2929
3030First, check what Skills are available. Use the Skills API to list all Anthropic-managed Skills. Each language tab is an excerpt from one continuous script, with any imports and client setup at the top:
3131
32<CodeGroup defaultLanguage="CLI">
32<CodeGroup>
3333 ```bash cURL
3434 # List Anthropic-managed Skills
3535 curl --fail-with-body -sS "https://api.anthropic.com/v1/skills?source=anthropic" \
api/beta/messages/batches Changed · +2 / -2 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 1338
13381338
13391339 - `BetaToolChangeMCPToolReference object`
13401340
1341 Reference to a single MCP tool by its server and remote name — the
1341 Reference to a single MCP tool by its server and remote name; the
13421342 same `server_name`/`name` pair `mcp_tool_use` carries.
13431343
13441344 - `type: "mcp_tool_reference"`
from line 1380
13801380
13811381 - `BetaToolChangeMCPToolReference object`
13821382
1383 Reference to a single MCP tool by its server and remote name — the
1383 Reference to a single MCP tool by its server and remote name; the
13841384 same `server_name`/`name` pair `mcp_tool_use` carries.
13851385
13861386 - `BetaToolChangeMCPToolsetReference object`
from line 8292
82928292
82938293 - `is_file_update: boolean`
82948294
8295 - `BetaTextEditorCodeExecutionStrReplaceResultBlock obj
8295 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object`
8296
8297
api/beta/messages/batches/create Changed · +2 / -2 lines
from line 1336
13361336
13371337 - `BetaToolChangeMCPToolReference object`
13381338
1339 Reference to a single MCP tool by its server and remote name — the
1339 Reference to a single MCP tool by its server and remote name; the
13401340 same `server_name`/`name` pair `mcp_tool_use` carries.
13411341
13421342 - `type: "mcp_tool_reference"`
from line 1378
13781378
13791379 - `BetaToolChangeMCPToolReference object`
13801380
1381 Reference to a single MCP tool by its server and remote name — the
1381 Reference to a single MCP tool by its server and remote name; the
13821382 same `server_name`/`name` pair `mcp_tool_use` carries.
13831383
13841384 - `BetaToolChangeMCPToolsetReference object`
api/beta/messages/count_tokens Changed · +2 / -2 lines
from line 1304
13041304
13051305 - `BetaToolChangeMCPToolReference object`
13061306
1307 Reference to a single MCP tool by its server and remote name — the
1307 Reference to a single MCP tool by its server and remote name; the
13081308 same `server_name`/`name` pair `mcp_tool_use` carries.
13091309
13101310 - `type: "mcp_tool_reference"`
from line 1346
13461346
13471347 - `BetaToolChangeMCPToolReference object`
13481348
1349 Reference to a single MCP tool by its server and remote name — the
1349 Reference to a single MCP tool by its server and remote name; the
13501350 same `server_name`/`name` pair `mcp_tool_use` carries.
13511351
13521352 - `BetaToolChangeMCPToolsetReference object`
api/beta/messages/create Changed · +2 / -2 lines
from line 1316
13161316
13171317 - `BetaToolChangeMCPToolReference object`
13181318
1319 Reference to a single MCP tool by its server and remote name — the
1319 Reference to a single MCP tool by its server and remote name; the
13201320 same `server_name`/`name` pair `mcp_tool_use` carries.
13211321
13221322 - `type: "mcp_tool_reference"`
from line 1358
13581358
13591359 - `BetaToolChangeMCPToolReference object`
13601360
1361 Reference to a single MCP tool by its server and remote name — the
1361 Reference to a single MCP tool by its server and remote name; the
13621362 same `server_name`/`name` pair `mcp_tool_use` carries.
13631363
13641364 - `BetaToolChangeMCPToolsetReference object`
api/beta/organization/mcp_tunnels/archive Changed · +2 / -1 lines
from line 28
2828
2929- `"anthropic-beta": array of AnthropicBeta`
3030
31 Optional header to specify the beta version(s) you want to use.
31 This endpoint is in beta: requests must send `mcp-tunnels-2026-05-19` in this header.
3232
3333 - `string`
3434
from line 174
174174curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/archive \
175175 -X POST \
176176 -H 'anthropic-version: 2023-06-01' \
177 -H 'anthropic-beta: mcp-tunnels-2026-05-19' \
177178 -H "X-Api-Key: $ANTHROPIC_API_KEY"
178179```
179180
api/beta/organization/mcp_tunnels/list Changed · +2 / -1 lines
from line 46
4646
4747- `"anthropic-beta": array of AnthropicBeta`
4848
49 Optional header to specify the beta version(s) you want to use.
49 This endpoint is in beta: requests must send `mcp-tunnels-2026-05-19` in this header.
5050
5151 - `string`
5252
from line 195
195195```bash
196196curl https://api.anthropic.com/v1/organizations/tunnels \
197197 -H 'anthropic-version: 2023-06-01' \
198 -H 'anthropic-beta: mcp-tunnels-2026-05-19' \
198199 -H "X-Api-Key: $ANTHROPIC_API_KEY"
199200```
200201
api/beta/organization/mcp_tunnels/retrieve Changed · +2 / -1 lines
from line 23
2323
2424- `"anthropic-beta": array of AnthropicBeta`
2525
26 Optional header to specify the beta version(s) you want to use.
26 This endpoint is in beta: requests must send `mcp-tunnels-2026-05-19` in this header.
2727
2828 - `string`
2929
from line 168
168168```bash
169169curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID \
170170 -H 'anthropic-version: 2023-06-01' \
171 -H 'anthropic-beta: mcp-tunnels-2026-05-19' \
171172 -H "X-Api-Key: $ANTHROPIC_API_KEY"
172173```
173174