Rotate a workspace API key

Rotate a workspace's API key with an organisation key: same key id, new secret shown once, and the old secret stops working within seconds.

Same key id, new secret. The old secret stops working within seconds everywhere, including open SMTP sessions. The workspace is told by email that one of its keys was rotated.

POST /v3/organisation/workspaces/{id}/keys/{key_id}/rotate

Response (200)

json

{
  "id": "3f6b2a9e-1c4d-4e8f-9a0b-5c6d7e8f9a0b",
  "name": "Acme EU production",
  "prefix": "afn_live_Qm2x",
  "scope": "send_only",
  "env": "live",
  "verify_before_send": null,
  "test_outcomes": null,
  "ip_allowlist": [],
  "last_used_at": "2026-10-29T11:02:10Z",
  "created_at": "2026-10-29T10:05:00Z",
  "key": "afn_live_Qm2xXXXXXXXXXXXXXXXX"
}

Responses

Status	Description
`200`	OK. The key with its new secret — shown only here.
`401`	Missing or invalid organisation key — workspace keys (`afn_live_` / `afn_test_`) are refused here by design.
`403`	`insufficient_scope` — the key lacks `keys:write` — or `ip_not_allowed`.
`404`	No such workspace or key in your organisation.

Code examples

cURL

curl -X POST https://api.wemail.io/v3/organisation/workspaces/9d2f6c1e-4b3a-4e7d-8a1f-0c5b7e9d2a64/keys/3f6b2a9e-1c4d-4e8f-9a0b-5c6d7e8f9a0b/rotate \
  -H "Authorization: Bearer afn_org_…"

Node.js

const res = await fetch("https://api.wemail.io/v3/organisation/workspaces/9d2f6c1e-4b3a-4e7d-8a1f-0c5b7e9d2a64/keys/3f6b2a9e-1c4d-4e8f-9a0b-5c6d7e8f9a0b/rotate", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.WEMAIL_ORG_KEY },
});
console.log(await res.json());

Python

import os, requests

res = requests.post(
    "https://api.wemail.io/v3/organisation/workspaces/9d2f6c1e-4b3a-4e7d-8a1f-0c5b7e9d2a64/keys/3f6b2a9e-1c4d-4e8f-9a0b-5c6d7e8f9a0b/rotate",
    headers={"Authorization": "Bearer " + os.environ["WEMAIL_ORG_KEY"]},
)
print(res.json())

ResponseExample response

{
  "id": "3f6b2a9e-1c4d-4e8f-9a0b-5c6d7e8f9a0b",
  "name": "Acme EU production",
  "prefix": "afn_live_Qm2x",
  "scope": "send_only",
  "env": "live",
  "verify_before_send": null,
  "test_outcomes": null,
  "ip_allowlist": [],
  "last_used_at": "2026-10-29T11:02:10Z",
  "created_at": "2026-10-29T10:05:00Z",
  "key": "afn_live_Qm2xXXXXXXXXXXXXXXXX"
}