Skip to main content

Creating an API key

An API key identifies your account to the agent. It is what lets a new machine register itself. It is not what a machine uses to report telemetry — each machine gets its own credential once it registers.

Create one​

  1. Sign in and go to Account Settings → Security.
  2. Find the API keys card and select Create key.
  3. Give it a name. This is for you, not the system — name it after where it will be used: laptop, office-rack, client-acme.
  4. Optionally set an expiry, between 1 and 365 days. Leave it blank and the key works until you revoke it.
  5. Select Create.

Copy it now​

The key appears once, in a dialog, with a copy button. It looks like:

wt_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Watchtower stores it hashed and cannot show it to you again. The list afterwards shows only the name, a masked prefix, and when it was created, expires, and was last used.

If you lose a key, delete it and create another. There is no recovery.

Keys have no scopes​

A key does one thing: register machines into your account. There is no read-only key, no per-machine key, and no permission dropdown. What limits a key is where it can be used — see IP rules — and when it expires.

How many keys should you have?​

As many as you have meaningfully separate places you install agents. There is no limit.

Separate keys are worth it because revoking one does not disturb the others, and because the last used column tells you whether a key is still in play before you delete it.

Reasonable splits:

  • One per site or office.
  • One per client, if you manage machines for other people.
  • A short-expiry key for a batch rollout, left to expire on its own afterwards.

What you should not do is use one key everywhere and never rotate it. If it leaks, every future machine registration is available to whoever has it, and your only remedy is to revoke it and revisit every machine you still want to add.

Machines already registered are unaffected by key changes​

Deleting or expiring a key does not disconnect the machines that registered with it. Each machine holds its own credential. The key controls adding machines, not keeping them.

The exception is IP rules, which are re-checked against machines that registered with the key — see IP rules.

To stop a specific machine reporting, revoke the machine: Revoking a machine.

Next​