Customer-managed keys (CMEK)

CMEK double-encrypts secrets. You encrypt the value with your own AES-256-GCM key in the browser or your process, then 1Claw applies its HSM envelope encryption on top. Your key never touches the server; only its SHA-256 fingerprint is stored so the vault knows which key was used. CMEK is available on Business and Enterprise plans.

1. 1

   Install the SDK and have an API key ready.

   bash Copy

   npm install @1claw/sdk

2. 2

   Export your API key and vault ID. Replace with your real values from Settings → API Keys and 1claw vault list.

   bash Copy

   export ONECLAW_API_KEY="1ck_your_key_here"
   export ONECLAW_VAULT_ID="your-vault-uuid"

3. 3

   Exchange your API key for a bearer token.

   bash Copy

   export TOKEN=$(curl -s -X POST https://api.1claw.co/v1/auth/api-key-token \
     -H "Content-Type: application/json" \
     -d "{\"api_key\":\"$ONECLAW_API_KEY\"}" | jq -r .access_token)

4. 4

   Save the code below as cmek-demo.ts. It generates a 256-bit key, encrypts a secret, stores it, reads it back, and decrypts it. Store the key safely because you need it for every read and write.

   typescript Copy

   import {
     createClient,
     generateCmekKey,
     cmekFingerprint,
     cmekEncrypt,
     cmekDecrypt,
     toBase64,
     fromBase64,
   } from "@1claw/sdk";
   
   const client = createClient({
     baseUrl: "https://api.1claw.co",
     apiKey: process.env.ONECLAW_API_KEY!,
   });
   
   const vaultId = process.env.ONECLAW_VAULT_ID!;
   
   async function main() {
     // Every CMEK helper is async and works on bytes.
     const key = await generateCmekKey();
     console.log("fingerprint:", await cmekFingerprint(key));
   
     // cmekEncrypt takes (plaintext, key): plaintext first.
     const plaintext = new TextEncoder().encode("sk-live-secret-value");
     const blob = await cmekEncrypt(plaintext, key);
   
     // secrets.set takes the value as a positional argument.
     await client.secrets.set(vaultId, "api-keys/stripe", toBase64(blob), {
       type: "api_key",
     });
   
     const res = await client.secrets.get(vaultId, "api-keys/stripe");
     if (res.data) {
       const decrypted = await cmekDecrypt(fromBase64(res.data.value), key);
       console.log(new TextDecoder().decode(decrypted));
     }
   }
   
   main();

5. 5

   Copy the fingerprint value printed above into the curl body below. Enable CMEK on the vault by sending only the fingerprint.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/vaults/$ONECLAW_VAULT_ID/cmek \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"fingerprint":"<paste-fingerprint-from-above>"}'

The vault now requires your key for every value, and 1Claw cannot decrypt your secrets unilaterally.

Where this goes wrong in practice. CMEK moves a real risk from the provider to the customer, and the failures are consistently operational rather than cryptographic.

• No escrow. The most common CMEK incident is not theft, it is a laptop and an unrecoverable vault. Enrolment should be paired with a customer-controlled escrow before the first secret is written.
• Rotation is started and never finished. Server-assisted rotation runs in batches with progress tracking, and a job interrupted midway leaves secrets split across two keys. Both keys must be retained until the job reports completion.
• The fingerprint is mistaken for a backup. It is a SHA-256 of the key, which can verify a candidate but cannot reconstruct one. Teams have discovered this at exactly the wrong moment.
• Client-side encryption is bypassed by one integration. A single service that writes through the API without encrypting first leaves plaintext in a vault everyone believes is customer-encrypted, and nothing in the interface will point it out.