---
title: "Server-side secret rotation"
method: POST
path: "/v1/vaults/{vault_id}/secret-rotate/{path}"
tags: ["Secrets"]
---

# Server-side secret rotation

`POST /v1/vaults/{vault_id}/secret-rotate/{path}`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/vaults/{vault_id}/secret-rotate/{path}`
- Auth: HTTP bearer

Generates a cryptographically random value and stores it as a new
version of the secret. The previous version is preserved in history.
Requires rotate or write permission.

## Path parameters

- `vault_id` string, uuid, required
- `path` string, required

## Request body

- RotateSecretRequest
  - `length` integer: Length of the generated value (default 32)
  - `charset` 'hex' | 'base64' | 'alphanumeric' | 'ascii': Character set for the generated value (default hex)
  - `type` string: Override the secret type (defaults to existing secret's type)

## Response `201`

New version created with server-generated value

- SecretCreatedResponse: Returned when a secret is created or updated. Extends SecretMetadataResponse with an optional client_share for MPC vaults.
  - `id` string, uuid, required
  - `path` string, required
  - `type` string, required
  - `version` integer, required
  - `metadata` object
  - `created_at` string, date-time, required
  - `expires_at` string, date-time
  - `client_share` string: Base64-encoded client key share. Returned only for MPC 2-of-2 vaults. The client must store this share securely — it is not persisted server-side.

## Other responses

- `400`: Invalid request
- `404`: Resource not found

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/5fa0918f3b41?raw)