Tokens & security
Manage the tokens that authenticate a fleet's collectors and installs.
A fleet's collectors authenticate to Telflo with two credentials.
| Credential | Purpose |
|---|---|
| Install token | Delivered with the fleet's install commands: the Quick Deploy command and the container run command carry it, and for a downloaded bundle you set it on the host as the OPAMP_TOKEN environment variable. A collector authenticates with it when it first connects, and falls back to it if its fleet token becomes invalid. It does not expire and is not affected by token rotation. |
| Fleet token | A rotating bearer token issued at fleet creation with the expiry you choose. A connected collector receives it and uses it at runtime. Rotate and revoke it from the fleet's Tokens tab. |
The fleet's Tokens tab has two sections.
| Section | Contents |
|---|---|
| Fleet Tokens | The fleet's rotating tokens, with their creation and expiry dates, status, and recent activity. During a rotation, the outgoing token shows as the predecessor until the grace period ends. Rotate or revoke here. |
| Install Links | The time-limited Quick Deploy links generated when you install collectors: who generated each one, a masked value, its status and download history, and actions to copy the install command, extend the expiry (from 1 day up to never), or revoke the link. Revoking a link stops further downloads; collectors already installed are unaffected. |
Revealing a fleet's container run command discloses the install token, so each reveal is recorded in the token audit log, the same as viewing a token.
Expiry
You set the fleet token's expiry when you create the fleet: Never, 180 days, 1 year, or 2 years. The Fleet Tokens section shows the active token and its expiry.
Rotate a token
Rotating mints a new fleet token and schedules the current one for graceful retirement. Select Rotate token in the Fleet Tokens section, then choose the new token's expiry (Never, 180 days, 1 year, or 2 years) and the date the grace period ends; it defaults to 30 days from the rotation and must be on or before the new token's expiry. During the grace period, both tokens authenticate.
Telflo's supervisor-managed collectors switch to the new token automatically at a check-in shortly after the rotation, with no change on the hosts. A collector that restarts authenticates with its install token and receives the current fleet token on its next check-in. No reinstall is needed.
On a Kubernetes bridge fleet, the bridge does not pick up a rotated token automatically. After rotating, redeploy the bridge so it authenticates with the new token. See Kubernetes fleets.
Rotate the token when it is approaching expiry, or on a regular schedule.
Revoke a token
Revoking invalidates a fleet token, and collectors using it are rejected at check-in within moments. A collector that reconnects with its install token, for example after a supervisor restart, stays enrolled and visible in the fleet, but Telflo stops delivering configuration to it: its last applied configuration keeps running unchanged, telemetry included. A newly installed collector receives no configuration beyond its bundled starter config. Configuration delivery resumes when you rotate to issue a new fleet token. Revoking the only valid fleet token stops configuration delivery for the whole fleet this way; it does not stop the collectors or their telemetry.
If an install artifact leaks, revoke its Quick Deploy link from the Install Links section, and re-create the fleet if the install token itself is exposed. A fleet whose install token has been revoked or has expired must be re-created.
Quick Deploy links can be revoked individually from the Install Links section.
Kubernetes fleet tokens
A Kubernetes bridge fleet has one fleet token, created with the fleet and embedded in the bridge install command shown in the fleet's deploy steps. There is no expiry choice at creation, and the raw token can be copied from the Tokens tab. Rotation is available, and a deployed bridge keeps its installed token, so redeploy the bridge after rotating. Re-create the fleet only when no valid token remains. See Kubernetes fleets.
Recommendations
- Keep install commands, tokens, and Quick Deploy links out of source control and shared documents. They are credentials. On installed hosts, the token is stored in the bundle's
opamp.envfile, readable by root only; treat that file as a secret. - Set a bounded expiry rather than Never for long-lived fleets, and rotate on a schedule.
- For credentials inside your configurations, such as backend API keys, reference environment variables with
${env:NAME}so the values come from the host environment and are not embedded in the YAML you publish. See Vault.
Last updated on