Enrollment tokens

An enrollment token is what the Add Collector wizard hands you to paste on a new host. The host presents it as a Bearer credential on its control-channel connection to the server; the server validates it and binds the host’s identity server-side. There is no client certificate and no operator password on the host.

How enrollment works

The handshake is designed so that an unused token is low-risk and a used one is durable:

1. Mint. A freshly minted token is un-redeemed. It carries a short expiry and is swept if it’s never used — so a token that leaks before anyone installs it stops working on its own, limiting the blast radius of a leaked-but-unused token.
2. First presentation. When a host first presents the token, the server validates it and binds it to that collector’s identity. At that moment it also pushes the token’s expiry far into the future, so the redeemed token escapes the short-TTL sweep and becomes durable.
3. Re-presentation. The host re-presents the same token on every reconnect — after a collector restart, a network blip, or a server restart or upgrade. Because a redeemed token is durable, the fleet reconnects on its own with no operator action. This is why a server restart doesn’t orphan the fleet.
4. Bound identity. A re-presented token can only ever authenticate as the same collector it was bound to on first redemption. It can’t be replayed against the server to impersonate a different collector.

Un-redeemed vs redeemed

Only un-redeemed tokens expire quickly. The moment a host redeems a token it becomes that host’s durable reconnect credential and stays valid until you revoke it or deregister the collector.

Lifecycle

Stage	Detail
Mint	The wizard calls POST /api/v1/enrollment-tokens. A freshly minted, un-redeemed token has a short expiry and is reaped if it’s never used.
Install	You paste the token into the host’s config, where it persists — the agent’s config.yaml (server.token), the OpAMP supervisor’s supervisor.yaml (Authorization: "Bearer …"), or Alloy’s config.alloy (remotecfg.bearer_token).
Present	The host sends Authorization: Bearer <token> on every (re)connect. The server validates it and binds the host’s identity — a specific collector, or a fleet. No certificate is issued.
Redeem → durable	On first redemption the token is bound to the collector it enrolled and becomes that host’s durable reconnect credential — it keeps working across collector and server restarts. Only un-redeemed tokens expire.
Single-use vs reusable	Single-use by default: it enrols exactly one host, then serves as that host’s reconnect credential — it can’t enrol a different host. A reusable token (for Kubernetes fleets) enrols many hosts, each getting its own collector identity.
Revoke	Delete the token, or deregister the collector, to cut the host off. It can no longer connect and must be re-enrolled with a fresh token.

Reconnection

Once a host is enrolled, its token is the credential it re-presents every time it reconnects — after a collector restart, a network blip, or a server upgrade. That’s why a redeemed token is durable: it has to outlive the short mint-time expiry so the fleet reconnects on its own after any restart, with no operator action. Treat the host’s config file accordingly — it holds a long-lived credential, not a one-shot code.

Scope

An enrollment token authenticates the agent control channel only. It cannot:

• Authenticate UI sessions
• Mint additional tokens
• Modify pipelines or routes
• Call the REST API

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. An un-redeemed token expires quickly — but once a token is installed on a host it is a durable credential: anyone who can read that host’s config can impersonate the collector until you revoke it.

• Copy from the wizard, paste directly into the target host’s config or terminal.
• Pass it to the installer from a shell variable — --token "$TOKEN" — rather than pasting the literal value, so it doesn’t linger in your shell history.
• For automation (Ansible, Terraform), mint one token per host and install it directly into that host’s config.

Regenerating

If a token expires before you redeem it, click + Add Collector again — a fresh token costs nothing. To rotate the credential on an already-enrolled host, mint a new token and update the host’s config, or deregister the collector and re-enrol it.

Where it lives

Surface	Path
UI	+ Add Collector wizard (header bar, or Collect → Collectors page)
API	POST /api/v1/enrollment-tokens to mint; the host then presents the token as Authorization: Bearer on its control-channel connection
On the host	the runtime’s config file — the agent’s config.yaml (server.token), the OpAMP supervisor’s supervisor.yaml, or Alloy’s config.alloy (remotecfg.bearer_token)
Storage	MongoDB collection enrollment_tokens, audit-logged on mint

An un-redeemed token lives only briefly — it’s minted, and if it isn’t used before its expiry it’s reaped. Once a host redeems it, the row becomes that host’s durable reconnect credential and stays until you revoke it or deregister the collector.

See also

• Add a collector — the operator walk-through
• Collector — what enrolment actually creates
• Credentials & tokens — how the enrollment token relates to the other three credential types
• How the edge talks to the server — the control channel the token authenticates
• Security & encryption — the trust model and how secrets are stored at rest
• Troubleshooting enrollment — what to do when redemption fails