Vaults, Secrets, and Envelope Encryption

A vault is a container for secrets. A secret is a value stored at a path like api-keys/openai. Every time you write to a path, 1Claw keeps the old value and bumps the version, so you always have history.

• Vault: isolated container, has its own HSM key encryption key (KEK)
• Secret: value at a slash-separated path (api-keys/stripe, passwords/db)
• Version: every write creates a new version, newest wins on read
• Types: api_key, password, private_key, certificate, ssh_key, note, env_bundle

1. 1

   Reuse the key you exported in Lesson 1. If it's still in your shell, skip this step.

   bash Copy

   export ONECLAW_API_KEY="1ck_your_key_here"

2. 2

   Get an access token and save it as 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)

3. 3

   Create a vault and auto-extract the vault ID. Requires jq (brew install jq or apt install jq).

   bash Copy

   export VAULT_ID=$(curl -s -X POST https://api.1claw.co/v1/vaults \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"My Vault","description":"Secrets for my app"}' | jq -r .id)
   echo "VAULT_ID=$VAULT_ID"

4. 4

   Store a secret at a path inside that vault.

   bash Copy

   curl -s -X PUT "https://api.1claw.co/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"type":"api_key","value":"sk-proj-demo"}'

5. 5

   Read it back. The response includes the decrypted value plus metadata like version.

   bash Copy

   curl -s "https://api.1claw.co/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
     -H "Authorization: Bearer $TOKEN"

You've now created a vault, written a secret to a path, and read the decrypted value back. That round trip is the whole 1Claw data model in action.