---
title: "Generate (or rotate) the project's HMAC data-plane secret and re-roll the engine (owner/admin). Returns the secret ONCE — it cannot be retrieved again."
method: POST
path: "/v1/projects/{project_id}/hmac-secret/rotate"
tags: ["projects"]
---

# Generate (or rotate) the project's HMAC data-plane secret and re-roll the engine (owner/admin). Returns the secret ONCE — it cannot be retrieved again.

`POST /v1/projects/{project_id}/hmac-secret/rotate`

## Request

- Base URL: `https://api.wavehouse.cloud`
- URL: `https://api.wavehouse.cloud/v1/projects/{project_id}/hmac-secret/rotate`
- Auth: one of:
  - API key in cookie `whc_session`
  - HTTP bearer
  - API key in header `X-API-Key`

## Path parameters

- `project_id` string, required

## Headers

- `Idempotency-Key` string: A unique value you choose per logical request (a random UUID). A retry with the same key and the same request within 24 hours returns the first response, marked Idempotency-Replayed: true, instead of acting twice. The same key with a different request is refused with 422; one sent while the first is still running gets 409.

## Response `201`

Created

- RotateProjectHMACSecretOutput
  - `auth_mode` string, required: the project's data-plane auth mode after this call (hmac)
  - `secret` string, required: the new HS256 signing key — shown ONCE. Store it now; it cannot be retrieved again (rotate to replace a lost one).

## Other responses

- `429`: Rate limited, per client IP, API key or org; a client IP is also refused on every route for a while after repeated authentication failures. A limited operation carries RateLimit-Policy and RateLimit on every response; wait Retry-After seconds before retrying.
- `default`: Error

---

[API](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api.md) · [All operations](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api/revisions/adea029bf505?raw)