Rotate an API key

Rotate an API key in place and receive its new secret once.

Replaces the key's secret in place: the key keeps its id, name, scope, environment and IP allowlist, but gets a brand-new secret and prefix. The previous secret stops working immediately — auth caches are invalidated fleet-wide within seconds. The account owner is notified by email with the old and new prefixes.

POST /v3/keys/{id}/rotate

Response (200)

json
{
  "id": "key_01j9…",
  "name": "Production API Key",
  "prefix": "afn_live_Xm2v",
  "scope": "full_access",
  "env": "live",
  "key": "afn_live_Xm2vXXXXXXXXXXXXXXXX",
  "verify_before_send": null,
  "test_outcomes": null,
  "ip_allowlist": [],
  "created_at": "2026-08-22T10:00:00Z"
}

Responses

StatusDescription
200Rotated. The response carries the new full secret in key — shown exactly once.
401Missing, invalid or revoked API key / session.
403Insufficient role or scope — see "Who can rotate".
404The key does not exist, belongs to another account, or is revoked.

Code examples

cURL
curl -X POST https://api.wemail.io/v3/keys/{id}/rotate \
  -H "Authorization: Bearer afn_live_…"
Node.js
const res = await fetch("https://api.wemail.io/v3/keys/{id}/rotate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WEMAIL_API_KEY}`,
  },
});
const data = await res.json();
Python
import os, requests

r = requests.post(
    "https://api.wemail.io/v3/keys/{id}/rotate",
    headers={"Authorization": f"Bearer {os.environ['WEMAIL_API_KEY']}"},
)
data = r.json()