Repository Public
1---2title: Configure Google Cloud KMS for CMEK3url: https://platform.claude.com/docs/en/manage-claude/cmek-google-cloud-kms4description: Use Google Cloud KMS to provide an encryption key for your organization.5---67```bash Configure with the /claude-api skill in Claude Code8claude "/claude-api help me configure a customer-managed encryption key with Google Cloud KMS"9```1011This guide walks through configuring a Google Cloud KMS key as a [customer-managed encryption key (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek) for your Anthropic organization.1213<Warning>14 Enabling CMEK is permanent. If your KMS key is deleted or disabled, Anthropic cannot recover the data encrypted under it. Review the [warnings and limitations](https://platform.claude.com/docs/en/manage-claude/cmek) before you begin.15</Warning>1617## Prerequisites1819* A Google Cloud project with billing enabled.20* The Cloud KMS API enabled (`cloudkms.googleapis.com`).21* Permissions to create KMS key rings and keys, and to set IAM policy on them (`roles/cloudkms.admin` or equivalent).22* An Anthropic Admin API key for your organization.23* The [`gcloud` CLI](https://cloud.google.com/cli) installed and authenticated.24* Cloud KMS **Data Access audit logs** enabled for the project (IAM & Admin > Audit Logs > Cloud Key Management Service, with `DATA_READ` and `DATA_WRITE`). These are off by default; without them, Anthropic's encrypt and decrypt operations produce no entries in Cloud Logging.2526## Anthropic service account email2728To have Anthropic use your encryption key, you must give Anthropic's service account a key it can use for encrypting data. The service account email for Anthropic CMEK is:2930```text wrap31anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com32```3334<Warning>35 Use only this published service account email. Never trust an identifier provided over email, chat, or any onboarding channel.36</Warning>3738<Note>39 **Domain restricted sharing:** If your project is under a Google Cloud organization that enforces `constraints/iam.allowedPolicyMemberDomains`, the following IAM bindings are rejected because the Anthropic service account is outside your organization. You need either a project-level carve-out on that constraint, or to add Anthropic's Cloud Identity customer ID (format `C0xxxxxxxx`) to the allowed list. Contact Anthropic for the customer ID if needed.40</Note>4142## Encryption key setup4344<Steps>45 <Step title="Create or choose a key ring">46 Skip this step if you already have a key ring to reuse. Key rings are regional. Choose a single-region US location such as `us-east5` that matches the Anthropic geography you are configuring. Multi-region locations like `us` and `global` are not supported.4748 ```bash49 gcloud kms keyrings create <your-keyring-name> \50 --project=<your-project-id> \51 --location=<region>52 ```53 </Step>5455 <Step title="Create the crypto key">56 Create a symmetric key with the `ENCRYPT_DECRYPT` purpose. Anthropic strongly recommends HSM protection: Cloud KMS HSM keys are FIPS 140-2 Level 3 validated, and the cost delta over software keys is small.5758 ```bash59 gcloud kms keys create <your-key-name> \60 --project=<your-project-id> \61 --location=<region> \62 --keyring=<your-keyring-name> \63 --purpose=encryption \64 --protection-level=hsm65 ```6667 For software protection instead, omit `--protection-level=hsm`. Nothing else in this guide changes.6869 You can also create the key from the Google Cloud Console. Open the key ring, click **Create key**, select **Generated key**, set the purpose and algorithm to symmetric encrypt and decrypt, and choose **HSM** under protection level.7071 <Frame caption="Create an HSM-protected symmetric encrypt/decrypt key.">72 73 </Frame>74 </Step>7576 <Step title="Grant Anthropic's service account access to the key">77 Two key-level IAM bindings are required. Both are scoped to the single crypto key, not project-wide or keyring-wide.7879 Encrypt and decrypt, which Anthropic uses to encrypt and decrypt the data keys that protect your workspace data (envelope encryption):8081 ```bash82 gcloud kms keys add-iam-policy-binding <your-key-name> \83 --project=<your-project-id> \84 --location=<region> \85 --keyring=<your-keyring-name> \86 --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \87 --role=roles/cloudkms.cryptoKeyEncrypterDecrypter88 ```8990 Viewer, for the metadata read (`cryptoKeys.get`) Anthropic performs at startup to validate the key's purpose and algorithm:9192 ```bash93 gcloud kms keys add-iam-policy-binding <your-key-name> \94 --project=<your-project-id> \95 --location=<region> \96 --keyring=<your-keyring-name> \97 --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \98 --role=roles/cloudkms.viewer99 ```100101 From the Console, select the key, open the **Permissions** panel, click **Grant access**, and add the service account with both the Cloud KMS CryptoKey Encrypter/Decrypter and Cloud KMS Viewer roles. Make sure you are on the key's permissions page, not the key ring or project, so the grant is scoped to this key only.102103 <Frame caption="Grant the Anthropic service account both roles, scoped to the key.">104 105 </Frame>106 </Step>107108 <Step title="Note the full key resource name">109 You pass this to Anthropic when you register the key. The format is:110111 ```text wrap112 projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>113 ```114115 Retrieve it with:116117 ```bash118 gcloud kms keys describe <your-key-name> \119 --project=<your-project-id> \120 --location=<region> \121 --keyring=<your-keyring-name> \122 --format="value(name)"123 ```124125 From the Console, open the key's details page and click **Copy resource name**.126127 <Frame caption="Copy the key's full resource name from the actions menu.">128 129 </Frame>130 </Step>131</Steps>132133## Register the key with Anthropic134135How you register the key depends on which product you use.136137<Tabs>138 <Tab title="Claude Platform">139 You can set up the key in the Claude Console or through the Admin API, with the same result.140141 <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>147148 <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>151152 <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>157158 <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.162163 <CodeGroup>164 ```bash cURL165 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 ```178179 ```bash CLI180 ant beta:organization:external-keys create <<'YAML'181 display_name: "<friendly-name>"182 geo: us183 provider_config:184 type: gcp185 key_name: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"186 YAML187 ```188189 ```python Python190 client = anthropic.Anthropic()191192 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 )200201 print(f"id: {external_key.id}")202 print(f"display_name: {external_key.display_name}")203 ```204205 ```typescript TypeScript206 const client = new Anthropic();207208 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 });217218 console.log(`id: ${externalKey.id}`);219 console.log(`display_name: ${externalKey.display_name}`);220 ```221222 ```csharp C#223 using Anthropic.Models.Beta.Organization.ExternalKeys;224225 AnthropicClient client = new();226227 var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()228 {229 DisplayName = "<friendly-name>",230 Geo = Geo.Us,231 ProviderConfig = new BetaGcpExternalKeyConfig232 {233 KeyName = "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"234 }235 });236237 Console.WriteLine($"id: {externalKey.ID}");238 Console.WriteLine($"display_name: {externalKey.DisplayName}");239 ```240241 ```go Go242 client := anthropic.NewClient()243244 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)255 }256257 fmt.Printf("id: %s\n", externalKey.ID)258 fmt.Printf("display_name: %s\n", externalKey.DisplayName)259 ```260261 ```java Java262 import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;263264 void main() {265 AnthropicClient client = AnthropicOkHttpClient.fromEnv();266267 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);273274 IO.println("id: " + externalKey.id());275 IO.println("display_name: " + externalKey.displayName().orElseThrow());276 }277 ```278279 ```php PHP280 use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;281 // ...282283 $client = new Client();284285 $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 );293294 echo "id: {$externalKey->id}\n";295 echo "display_name: {$externalKey->displayName}\n";296 ```297298 ```ruby Ruby299 client = Anthropic::Client.new300301 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 )309310 puts "id: #{external_key.id}"311 puts "display_name: #{external_key.display_name}"312 ```313 </CodeGroup>314315 The response contains the external key ID:316317 ```json318 {319 "type": "external_key",320 "id": "ekey_<id>",321 "display_name": "<friendly-name>"322 }323 ```324 </Step>325326 <Step title="Validate the key">327 Trigger an encrypt and decrypt round-trip against your key.328329 <CodeGroup>330 ```bash cURL331 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 ```335336 ```bash CLI337 ant beta:organization:external-keys validate --external-key-id "ekey_<id>"338 ```339340 ```python Python341 client = anthropic.Anthropic()342343 validation = client.beta.organization.external_keys.validate("ekey_<id>")344345 print(f"status: {validation.status}")346 print(f"error: {validation.error}")347 ```348349 ```typescript TypeScript350 const client = new Anthropic();351352 const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");353354 console.log(`status: ${validation.status}`);355 console.log(`error: ${validation.error}`);356 ```357358 ```csharp C#359 AnthropicClient client = new();360361 var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");362363 Console.WriteLine($"status: {validation.Status.Raw()}");364 Console.WriteLine($"error: {validation.Error}");365 ```366367 ```go Go368 client := anthropic.NewClient()369370 validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")371 if err != nil {372 log.Fatal(err)373 }374375 fmt.Printf("status: %s\n", validation.Status)376 fmt.Printf("error: %s\n", validation.Error)377 ```378379 ```java Java380 AnthropicClient client = AnthropicOkHttpClient.fromEnv();381382 var validation = client.beta().organization().externalKeys().validate("ekey_<id>");383384 IO.println("status: " + validation.status().asString());385 IO.println("error: " + validation.error().orElse(""));386 ```387388 ```php PHP389 $client = new Client();390391 $validation = $client->beta->organization->externalKeys->validate(392 externalKeyID: 'ekey_<id>',393 );394395 echo "status: {$validation->status}\n";396 echo "error: {$validation->error}\n";397 ```398399 ```ruby Ruby400 client = Anthropic::Client.new401402 external_key_id = "ekey_<id>"403 validation = client.beta.organization.external_keys.validate(external_key_id)404405 puts "status: #{validation.status}"406 puts "error: #{validation.error}"407 ```408 </CodeGroup>409410 A successful response looks like this:411412 ```json413 { "type": "external_key_validation", "status": "success", "error": null }414 ```415416 If validation fails, common causes are:417418 * **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>422423 <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).425426 <CodeGroup>427 ```bash cURL428 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 ```436437 ```bash CLI438 ant beta:organization:workspaces update \439 --workspace-id "<workspace-id>" \440 --external-key-id "ekey_<id>"441 ```442443 ```python Python444 client = anthropic.Anthropic()445446 workspace = client.beta.organization.workspaces.update(447 "<workspace-id>", external_key_id="ekey_<id>"448 )449450 print(f"id: {workspace.id}")451 print(f"external_key_id: {workspace.external_key_id}")452 ```453454 ```typescript TypeScript455 const client = new Anthropic();456457 const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {458 external_key_id: "ekey_<id>"459 });460461 console.log(`id: ${workspace.id}`);462 console.log(`external_key_id: ${workspace.external_key_id}`);463 ```464465 ```csharp C#466 AnthropicClient client = new();467468 var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()469 {470 ExternalKeyID = "ekey_<id>"471 });472473 Console.WriteLine($"id: {workspace.ID}");474 Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");475 ```476477 ```go Go478 client := anthropic.NewClient()479480 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)489 }490491 fmt.Printf("id: %s\n", workspace.ID)492 fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)493 ```494495 ```java Java496 import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;497498 void main() {499 AnthropicClient client = AnthropicOkHttpClient.fromEnv();500501 var params = WorkspaceUpdateParams.builder()502 .externalKeyId("ekey_<id>")503 .build();504 var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);505506 IO.println("id: " + workspace.id());507 IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());508 }509 ```510511 ```php PHP512 $client = new Client();513514 $workspace = $client->beta->organization->workspaces->update(515 workspaceID: '<workspace-id>',516 externalKeyID: 'ekey_<id>',517 );518519 echo "id: {$workspace->id}\n";520 echo "external_key_id: {$workspace->externalKeyID}\n";521 ```522523 ```ruby Ruby524 client = Anthropic::Client.new525526 workspace_id = "<workspace-id>"527 workspace = client.beta.organization.workspaces.update(528 workspace_id,529 external_key_id: "ekey_<id>"530 )531532 puts "id: #{workspace.id}"533 puts "external_key_id: #{workspace.external_key_id}"534 ```535 </CodeGroup>536 </Step>537 </Steps>538 </Tab>539 </Tabs>540 </Tab>541542 <Tab title="Claude Enterprise">543 In [claude.ai > Organization settings > Data and privacy](https://claude.ai/admin-settings/data-privacy-controls), open **Encryption keys**, then click **Add key**. Choose **Google Cloud**, paste the full key resource name from the previous step, and click **Continue**. Anthropic validates the key with an encrypt and decrypt round-trip. Once it shows as verified, your organization is CMEK-protected from that point forward.544545 On Claude Enterprise, CMEK applies to the whole organization, so there is no separate workspace attach step, and an organization can have only one key.546 </Tab>547</Tabs>548549## Terraform550551For infrastructure-as-code deployments, the same steps map to the `google` provider with the `google_kms_key_ring`, `google_kms_crypto_key`, and `google_kms_crypto_key_iam_member` resources.552