Enrollment tokens

An enrollment token is what the Add Collector wizard hands you to paste on a new host. It’s a short-lived, single-use credential that lets the host bootstrap its mTLS client certificate against your server without exposing your operator password.

Lifecycle

Stage	Detail
Mint	The wizard calls POST /api/v1/enrollment-tokens against your server. Server records the new token in the audit log with the operator’s identity.
TTL	Default 15 minutes. Configure with --ttl when minting via CLI; configurable per-server via config.yaml.
Single-use	One successful enrollment consumes the token. A second attempt with the same token returns 410 Gone.
Redeem	The host’s installer POSTs the token to /api/v1/bootstrap. Server returns a CA cert, a fresh client cert, and the collector ID.
Expire	If 15 minutes passes without redemption, the token expires silently. Mint a new one.

Scope

Each token is scoped to creating exactly one collector. It cannot:

• Authenticate UI sessions
• Mint additional tokens
• Modify pipelines or routes
• Reach any API endpoint other than /api/v1/bootstrap

That’s intentional — a token leaked in shell history grants the attacker the ability to enrol one collector, not full control of your fleet.

Treat tokens like passwords

Caution

Don’t commit tokens to git, paste them in chat, or leave them in CI logs. They expire fast, but a leaked token before expiry is enough to enrol a rogue collector against your fleet.

• Copy from the wizard, paste directly into the target host’s terminal, close the wizard.
• Use sudo -E to preserve LINKMESH_TOKEN from your env so it doesn’t enter shell history.
• For automation (Ansible, Terraform), mint a token via the API per host, redeem immediately, never persist.

Regenerating

If a token expires before you finish, just click + Add Collector again — a fresh token costs nothing. Old expired tokens stay in the audit log so you can trace who tried what.

Where it lives

Surface	Path
UI	+ Add Collector wizard (header bar, or Collect → Collectors page)
API	POST /api/v1/enrollment-tokens to mint, POST /api/v1/bootstrap to redeem
Storage	MongoDB collection enrollment_tokens — short-lived rows, single use, audit-logged on mint and on redemption

The token itself only exists in flight: minted into the wizard, copied to a host, redeemed, deleted. After redemption the row is kept in the audit log for traceability but the token value is no longer accepted.

See also

• Add a collector — the operator walk-through
• Collector — what enrolment actually creates
• Troubleshooting enrollment — what to do when redemption fails