Versioning and Rotation

Every write to a path creates a new version and keeps the old ones. You can rotate in two ways: PUT a new value yourself, or have the vault generate a random one server-side so the plaintext never touches your client.

• Client-supplied: PUT a new value to the same path, creating a new version
• Server-side: POST to secret-rotate, the vault generates and stores the value
• List: GET secret-versions returns all versions newest first with is_disabled
• Disable: a disabled version is kept for audit but reads return 410 Gone

1. 1

   Set your credentials. Use your 1ck_ key directly as a Bearer token, or exchange it at POST /v1/auth/api-key-token for a JWT (see Foundations). CLI steps assume you completed 1claw login from the Install the CLI lesson.

   bash Copy

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

2. 2

   Create the secret you will rotate. Skip this if it already exists from Foundations.

   bash Copy

   1claw secret set api-keys/db-password --value "old-password" --type password

3. 3

   Rotate with a client-supplied value by PUTting a new value to the same path. This creates a new version.

   bash Copy

   curl -s -X PUT "https://api.1claw.co/v1/vaults/$ONECLAW_VAULT_ID/secrets/api-keys%2Fdb-password" \
     -H "Authorization: Bearer $ONECLAW_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"value":"new-password-from-client","type":"password"}'

4. 4

   Or rotate server-side. The vault generates a random 32-char hex value and stores it as the next version. You never see or send the plaintext.

   bash Copy

   curl -s -X POST "https://api.1claw.co/v1/vaults/$ONECLAW_VAULT_ID/secret-rotate/api-keys%2Fdb-password" \
     -H "Authorization: Bearer $ONECLAW_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"length":32,"charset":"hex"}'

5. 5

   Or do the same from the CLI.

   bash Copy

   1claw secret rotate api-keys/db-password --generate --length 32 --charset hex

6. 6

   List versions to confirm a new one exists.

   bash Copy

   1claw secret versions api-keys/db-password

7. 7

   Disable an old version so any read of it returns 410 Gone. Pick the oldest non-disabled version number from the list output above and use it in place of 1.

   bash Copy

   curl -s -X POST "https://api.1claw.co/v1/vaults/$ONECLAW_VAULT_ID/secret-version-disable/api-keys%2Fdb-password/1" \
     -H "Authorization: Bearer $ONECLAW_API_KEY"

You've rotated a secret to a fresh version and listed its history. Consumers reading the latest version pick up the new value automatically, and old versions can be disabled without losing the audit trail.

Where this goes wrong in practice. Rotation is straightforward to perform and easy to sequence wrongly, and the wrong order causes an outage rather than a warning.

• The old version is disabled before consumers move. Rotation creates a new version and leaves the old one readable so both can coexist. Disabling immediately is what turns a rotation into an incident.
• Nobody knows who consumes the secret. Rotation is safe when you can enumerate the readers and unsafe when you cannot, and the audit log is the only reliable source for that list.
• Server-side generation is skipped. Generating a value yourself means it exists in your shell history, your clipboard and possibly your terminal scrollback before it ever reaches the vault.
• Rotation is treated as an incident response only. A credential rotated only after a suspected leak has no established procedure at the moment it is needed most.
• Disabling is confused with deleting. Disabling a version is reversible and preserves the record; deleting the key material is cryptographic erasure.