Security

How to Rotate and Expire Client API Keys

Rotate the API keys and service-account secrets you hold at project boundaries and after any personnel change, not on a nervous whim. Collecting keys through requests that expire turns each re-collection into a built-in rotation prompt.

Rotate the API keys and service-account secrets you hold at clear events, when a project ends, when someone with access leaves, and if a key may have leaked, rather than leaving them in place indefinitely. Collecting keys through requests that expire helps, because each re-collection is a natural moment to ask for a fresh key. This is different from forcing users to change passwords on a schedule, which is discouraged.

Why machine keys are worth rotating

An API key or service-account secret is shared, often long-lived, and usually broad in what it can do. The longer it sits unchanged and the more places it's been copied, the bigger the exposure if it leaks. Rotating it, replacing the old key with a new one, shrinks that window. This is not the same as the old advice to make people change their login passwords every 90 days, which pushes users toward weaker, patterned passwords and is now discouraged. Machine credentials are the case where rotation genuinely helps.

When to rotate

• At project boundaries. When a build ships or an engagement ends, rotate the keys you were given.
• On any personnel change. When a contractor or team member with access rotates off, rotate what they could reach.
• On suspected exposure. If a key was pasted somewhere it shouldn't have been, treat it as leaked and replace it.
• On a sensible cycle. For keys that stay in use, an annual refresh is reasonable, event-driven rotation just matters more than the calendar.

How expiry turns re-collection into rotation

A password manager stores a key until someone remembers to change it, which often means never. If instead you collect the client's keys through a request that expires, keeping the work going means re-collecting, and that re-collection is the prompt: you ask the client for a current key, and stale ones fall away on their own. Expiry, usually thought of as a limitation, does useful work here.

A simple rotation routine

1. Keep a per-project list of every key you hold, so rotation has a checklist.
2. Collect keys through an expiring request, so re-collection prompts a refresh.
3. Rotate at the events above, not on a nervous whim.
4. Confirm the old key is revoked at the source after the new one works.
5. Keep a record of what was rotated and when, for the client and for you.

Where doconvoy fits

doconvoy collects each project's keys through an encrypted request with an expiry you set, so nothing lingers unrotated the way it can in a stored-forever vault. The per-project record is your rotation checklist at handoff. See how the keys come in to begin with in how to collect API keys from clients securely.

Related: How to collect API keys from clients securely · API keys vs OAuth: how to get client access for automations · How to revoke access after you shared it · Access Controls

Common questions

How often should you rotate client API keys?

Rotate at clear events: when a project ends, when someone with access leaves, and if a key may have leaked. A periodic cycle (for example annually) is reasonable for long-lived machine keys, but event-driven rotation matters more than an arbitrary calendar.

Is rotating API keys the same as forcing password changes?

No. Forcing users to change memorised passwords on a schedule tends to backfire and is discouraged. Machine credentials like API keys and service-account secrets are different: they're shared, long-lived, and worth rotating, especially when access changes.

How does an expiring collection link help with rotation?

If you collect a client's keys through a request that expires, you have to re-collect to keep working, and re-collection is a natural moment to ask the client for a fresh key. A stored-forever vault never prompts that, so keys can sit unrotated for years.