Rotating secrets

1claw does not yet expose a dedicated "rotate" endpoint that returns a new value from a provider. Rotation is done by creating a new version of the secret.

Steps

1. Generate or obtain the new value (e.g. new API key from OpenAI, new DB password).
2. PUT to the same vault and path with the new value (see Create/update).
3. Update any consumers to use the new value (or rely on "latest" version).
4. Optionally revoke or expire the old value at the external provider.

How to rotate

curl

# Generate the new value, then store it at the same path
curl -X PUT "https://api.1claw.xyz/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"api_key","value":"sk-proj-NEW..."}'

TypeScript

// PUT to the same path creates a new version automatically
await client.secrets.set(vaultId, "api-keys/openai", "sk-proj-NEW...", {
  type: "api_key",
});

Optional: limit exposure

• Set expires_at on the secret so it becomes unavailable after a date.
• Set max_access_count so the secret stops being returned after N reads (e.g. one-time use).

Agent tokens

To rotate an agent API key, use POST /v1/agents/:agent_id/rotate-key. The response includes the new key once; update the agent's config and discard the old key.

curl

curl -X POST "https://api.1claw.xyz/v1/agents/$AGENT_ID/rotate-key" \
  -H "Authorization: Bearer $TOKEN"

TypeScript

const { data } = await client.agents.rotateKey(agentId);
console.log(data.api_key); // New key — store securely