Rotating keys
Why bother, given that
A key that never changes is a key whose exposure only grows. It is copied into a new deployment, pasted into a thread, inherited by someone who did not create it. Keys here never expire, so the only thing that ever ends that accumulation is you.
Rotation also rehearses the thing you will need in an incident. The first time you replace a production key should not be the morning you discover it has leaked.
The sequence
Two keys work at once, because they are simply two independent keys. That overlap is what makes this safe, and it is the only grace period available.
1. Create the replacement. Same scopes, a label that says which it is.
curl -X POST https://api.lockally.com/v1/api-keys \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"label":"production-backend-2026-10","scopes":["send:write","send:read"]}'
Date the label. When you are looking at four keys in a year’s time, the dates are what let you tell which is current.
2. Deploy it. Put the new secret in your secret store and roll it out. Both keys work, so there is no window where neither does.
3. Wait, and check it is actually in use. This is the step people skip.
curl -H "Authorization: Bearer $ADMIN_KEY" https://api.lockally.com/v1/api-keys
Watch last_used_at. You want the new key moving and the old key
going quiet. Until the old one has been idle across a full cycle of whatever
uses it, including anything that runs nightly or weekly, something is still
holding it.
4. Revoke the old one. Only now.
curl -X DELETE -H "Authorization: Bearer $ADMIN_KEY" \
https://api.lockally.com/v1/api-keys/{old-id}
5. Confirm. A Revoked API key error appearing in your logs after this
means something you forgot was still using it. That error names the date, so
it is easy to recognise.
Rotating from a script, and why it is awkward
You cannot fully automate this from one key, because a key cannot revoke
itself: that returns 409. So a script must either hold a separate
tenant:admin key to do the revoking, or leave step 4 to a human.
Giving a deployment tenant:admin so it can rotate its own credential is a
poor trade: that scope can mint keys with any scopes, so you have replaced a
narrow long-lived secret with a broad one. Prefer doing steps 1 and 4 from
the console, and let the deployment hold only what it needs.
After a suspected leak, invert the order
The sequence above minimises downtime. An exposed key is the opposite problem, so:
- Revoke the exposed key first. Accept the outage.
- Create a replacement and deploy it.
- Then work out what the key could reach while it was exposed: its
scopesand, for inbox keys, its mailbox grants.
A key in a public repository should be treated as used, not as possibly used.
last_used_at tells you when it was last exercised, which is a starting point
rather than an answer.
What would make this easier, and does not exist
Said plainly so you can plan around the absence:
| Key expiry | No expires_at. Keys live until revoked |
| Scheduled rotation | Nothing issues a successor on a timer |
| Scope changes | A key’s scopes are fixed, so widening costs a rotation too |
| Staleness reporting | last_used_at is the raw material; there is no report or alert |
Until these exist, put rotation in your own calendar. A quarterly review of
GET /v1/api-keys, revoking anything with a stale last_used_at, costs a few
minutes and is most of the benefit.