> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.dealsignal.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dealsignal.com/_mcp/server.

# 2026-05-20 — API key rotation & Authentication tag

> New `/api/v1/auth/api_keys` endpoints for zero-downtime key rotation.

## Added

### `POST /api/v1/auth/api_keys/roll`

Mint a new API key and park the current one with its own grace window (default 48 hours). Lets you rotate credentials without taking down a partially-deployed fleet.

* `api_key` **must** be in the request body. Passing it via query string returns `400`.
* Rate-limited per user — `429` with a `Retry-After` header on too-frequent rolls.
* Multiple rolled-away keys can be active at once; each has an independent `expires_at`.

See **[Authentication](/documentation/get-started/authentication)** for the full rotation flow.

### `GET /api/v1/auth/api_keys`

List the authenticated user's current key metadata plus any rolled-away previous keys still inside their grace windows. Plaintext is never returned.

### New `Authentication` tag

Both endpoints live under the new `Authentication` tag in the API Reference.

---

## Notes for clients

* If you script key rotation in CI, switch from putting `api_key` in the URL to putting it in the JSON body for the `roll` call.
* Honour `Retry-After` on `429` from `/api/v1/auth/api_keys/roll`.
* Multiple previous keys can be active simultaneously — design your "previous key" tracking around the array returned by `GET /api/v1/auth/api_keys`, not a single value.