Skip to main content

Rotating and revoking keys

Revoking a key​

Account Settings → Security → API keys, then Revoke on the key. You are asked to confirm.

Revoking is immediate and permanent. The key stops being able to register machines.

What revoking does not do​

It does not disconnect machines. Every machine that already registered holds its own credential and keeps reporting. Revoking a key closes the door to new machines; it does not evict the ones already inside.

To stop a machine reporting, revoke the machine — Revoking a machine.

Rotating a key​

Because keys are only read at registration, rotation is undramatic:

  1. Create a new key.
  2. Update your rollout scripts, service definitions, or install notes to use it.
  3. Revoke the old one.

There is no overlap window to manage and nothing goes offline in between. A machine mid-registration with the old key is the only thing that could fail, and it retries.

Check the last used column before revoking. If it shows a recent date you did not expect, something is still registering with that key.

When to rotate​

  • A key was exposed — pasted into a chat, committed to a repository, left in a shell history on a shared machine. Revoke first, create a replacement second; the gap only prevents new registrations.
  • Somebody with access to it left.
  • On a schedule, if that is your policy. Set an expiry when you create the key and it will rotate itself, provided you remember to issue a replacement.

Expiry​

A key with an expiry stops working on that date without any action from you. Machines registered with it are unaffected — again, they hold their own credentials.

Expiry is useful for a rollout: set 30 days, register your fleet, and let the key lapse rather than remembering to revoke it.

If you think a key was misused​

  1. Revoke the key.
  2. Look at Machines for records you do not recognise. A key used by somebody else would have created machines.
  3. Revoke any machine you did not add — Revoking a machine.
  4. Check the Security events tile on the Overview page for refused connections and duplicate machines around the time in question.
  5. Create a replacement key with IP rules this time.