Skip to main content

Keys and secrets

Watchtower uses two different credentials. Knowing which is which explains most of how enrollment and revocation behave.

Account API key​

Prefix wt_. You create it in Account Settings → Security.

It identifies your account and does exactly one thing: let a new machine enroll. It cannot connect to the broker, cannot read telemetry, and cannot be used to look at your machines.

You hold this one. It goes into the agent's environment on first run and is not read again.

Machine secret​

Prefix wtm_. You never see it and never type it.

Issued automatically when a machine enrolls, stored in the machine's credential file, and used for every connection after that. It is scoped to one machine. Holding it lets you report telemetry as that machine and nothing else — it cannot enroll new machines or read others.

Why the split​

If one credential did both jobs, a machine's copy would be enough to enroll more machines. Every laptop in your fleet would carry the ability to add machines to your account, and revoking any one of them would mean rotating all of them.

Splitting them means:

  • Revoking a machine affects one machine.
  • Revoking a key stops new enrollments and disturbs nothing already running.
  • A credential read off a stolen laptop cannot grow into account access.

Machines cannot claim to be each other​

A machine does not get to say which machine it is. Watchtower resolves the identity from the credential presented and uses that, ignoring any claim the agent makes. A stolen machine secret therefore cannot be used to impersonate a different machine — it can only be that one machine.

Accounts are isolated​

Every machine, key, and telemetry channel belongs to exactly one account. A connection cannot read, write to, or even name anything outside its own account. An agent presenting a valid credential while claiming to belong to a different account is refused and the attempt is recorded — see Security events.

Revocation is fast​

Revoking a machine drops its live connection in about a second rather than waiting for a credential to expire.

What is stored​

API keys are stored hashed, which is why the plaintext is shown once and never again. Machine secrets are issued to the machine and stored hashed on the server the same way.

Practical advice​

  • Put the API key in the agent's environment for the first run, then take it out. The credential is all it needs afterwards.
  • Use IP rules on any key that lives at a fixed site.
  • Set an expiry on keys used for one-off rollouts.
  • Never bake a credential file into a VM image — see Moving a machine.