Rotate a key

On this page

If a key leaks, or on a schedule, rotate it. The key in Authorization mints its successor with the same scopes; the old key keeps working for a grace window (24 hours unless you say otherwise, up to 168) so you can switch every service that holds it and restart them, then it answers 401 key_rotated. Any key can rotate itself, whatever its scopes. A key that has been rotated cannot rotate again; its successor can.

sh
curl -sS -X POST https://alg.katrinalaszlo.com/v1/keys/rotate \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "grace_hours": 24 }'

The answer is 201 with key (shown once), scopes, grace_until and a message saying what to do. ?format=env answers one AGENT_TRAFFIC_KEY= line instead, to replace the one in your .env. A project key rotates the same way and its successor keeps the project. The middleware reads the key when the process starts, so replacing the line is not enough: restart or redeploy every service before grace_until. While the old key is inside its grace window, every 202 it earns on POST /v1/events carries a warnings array saying when it stops working; the middleware logs that once per process.

If someone else rotated a leaked key, rotation alone does not get it back: they hold the successor. In the dashboard, under Settings, Workspace keys lists every workspace key that still works, with when it was made, its last four characters and which key it was rotated from. Signed in with your account, or with a key that has the write scope, you can Revoke any of them (it stops at once, even inside a grace window) except the key your browser signed in with, and Rotate now makes a new key with the same scopes and stops the old one at once, even one already inside a grace window.