Credentials & tokens

LinkMesh uses four distinct credentials, each for one job. Knowing which is which keeps rotation and revocation simple: you never have to guess what a given token unlocks or where it’s stored.

Credential	What it authenticates	Where it lives	Issued / rotated / revoked
Enrollment token	A collector or agent on its control channel	Host config (supervisor.yaml, config.alloy, or the agent’s LINKMESH_SERVER_TOKEN)	Minted in the Add Collector wizard; rotate by minting a new one; revoke by regenerating or deregistering the collector
Service-account token (lmsat_…)	The REST API for automation (CI, Terraform)	Your automation’s secret store / CI variables	Minted per service account; rotate by minting a new one and revoking the old; revoke in the UI or API
Per-collector own-metrics token	A collector pushing its self-telemetry to /v1/metrics	The collector’s own config, alongside its config-pull credential	Minted per collector at enrollment; rotate via POST /collectors/{id}/otlp-token (revokes the prior one)
UI session	A human in the web UI	The browser (session token)	Issued after a bcrypt password login; ends on logout or expiry

Everything the edge presents is a Bearer credential over TLS. There are no client certificates in the steady state, and no passwords on any managed host.

Enrollment token

The credential the Add Collector wizard hands you to paste on a new host. The host presents it as a Bearer credential on its control channel — /v1/opamp for OpAMP, bearer_token in config.alloy for Alloy, or LINKMESH_SERVER_TOKEN for the agent. A single-use token enrols exactly one collector; a reusable fleet token enrols many hosts, each becoming its own collector. Once a host redeems it, the token is that host’s durable reconnect credential. Revoke by regenerating or deleting the token, or by deregistering the collector.

Full detail — including the handshake and why a redeemed token survives server restarts — is in Enrollment tokens.

Service-account token

For the REST API and automation: CI jobs, Terraform, scripts. It carries the lmsat_ prefix and is scoped by its service account’s role, so you can grant an automation exactly the access it needs and no more. It is stored hashed — the raw value appears once at creation. Rotate by minting a fresh token and revoking the old one.

See Authenticate with a service account for the full workflow.

Per-collector own-metrics token

A Bearer token a collector uses to POST its own internal metrics to /v1/metrics, which is what powers the per-component throughput numbers on the topology canvas. It is minted per collector at enrollment and is independent of the enrollment token. Rotate it with POST /collectors/{id}/otlp-token, which mints a fresh token and revokes the prior one immediately.

See Self-telemetry for where it’s wired and what it carries.

UI session

A human logs into the web UI with an email and password; the password is verified against a bcrypt hash and the server issues a session (a JWT) for the browser. It authenticates the UI only — it never authenticates a collector, and it isn’t something you paste into a host config.

Treat every token like a password

Don’t commit tokens to git, paste them in chat, or leave them in CI logs. Enrollment tokens and per-collector tokens become durable credentials once installed on a host — anyone who can read that host’s config can act as that collector until you revoke it.

See also

• Destination secrets — the other kind of credential: the backend API keys and tokens your destinations use, kept encrypted and out of committed config.
• Security & encryption — the trust model these credentials fit into, and how secrets are stored at rest.
• Enrollment tokens — the enrollment credential in depth.
• Authenticate with a service account — minting and using lmsat_ tokens for the API.
• Self-telemetry — the per-collector own-metrics token in context.