---
title: "Rotate an API key's secret"
method: POST
path: "/api/projects/{id}/api-keys/{keyId}/rotate"
tags: ["API Keys"]
---

# Rotate an API key's secret

`POST /api/projects/{id}/api-keys/{keyId}/rotate`

## Request

- Base URL: `https://api.sendly.now`
- URL: `https://api.sendly.now/api/projects/{id}/api-keys/{keyId}/rotate`
- Auth: one of:
  - API key in cookie `better-auth.session_token`
  - OAuth 2 (authorization code, authorization URL `https://app.sendly.now/api/auth/oauth2/authorize`, token URL `https://app.sendly.now/api/auth/oauth2/token`, scopes: `api-keys:write`)

Replace the key's secret in place, keeping its id, name and scopes. The PREVIOUS secret stops authenticating immediately — there is no overlap window — so anything still using it starts failing on its next request. As with creation, the new secret is not returned: the response carries `lastFour` and a one-time `revealUrl`. A revoked key cannot be rotated (`400 KEY_REVOKED`).

Requires the `api-keys:write` scope — Create, rotate, and revoke API keys — these keep working even after you disconnect this app.

## Path parameters

- `id` string, required: Project id.
- `keyId` string, required: API key id.

## Response `200`

API key rotated; the new secret is behind the reveal link.

- object
  - `data` object, required
    - `lastFour` string, required
    - `revealExpiresAt` string, date-time, required: When the reveal link stops working. Create or rotate again to get a new one.
    - `revealUrl` string, uri, required: A one-time, session-authenticated URL where the person who owns this project can see the secret. The secret itself is never returned to an API or agent caller: opening this link requires a signed-in dashboard session, so the credential that created the key cannot redeem it. Single use — the first successful open consumes it.
  - `success` true, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized — missing or invalid auth
- `403`: Forbidden — insufficient permissions or project disabled
- `404`: Resource not found
- `429`: Rate limit or billing limit exceeded
- `500`: Internal server error

---

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