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 | Embedded in every install option: the supervisor bundle, the Quick Deploy URL, and the container run command. A collector authenticates with it when it first connects, and falls back to it if its client token becomes invalid. It does not expire and cannot be rotated or revoked. |
| Client 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 Client Tokens tab. |
The fleet detail page has two token tabs.
| Tab | Contents |
|---|---|
| Client Tokens | The client token collectors use at runtime, with its expiry. Rotate or revoke it here. |
| Deployment Tokens | The tokens behind generated Quick Deploy URLs: who generated each one, a masked value, and actions to copy the install command, extend the expiry, or revoke it. |
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 client token's expiry when you create the fleet: Never, 180 days, 1 year, or 2 years. The Client Tokens tab shows the active token and its expiry.
Rotate a token
Rotating mints a new client token and schedules the current one for graceful retirement. During the grace period (30 days by default), both tokens authenticate. Connected collectors switch to the new token automatically on their next check-in, with no change on the hosts. A collector that restarts, or returns after the grace period, authenticates with its install token and receives the current client token on its next check-in. No reinstall is needed.
On a Kubernetes 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 client token immediately. Collectors using it fall back to their install token on the next check-in: they stay connected, but they receive a placeholder configuration that processes no telemetry until you rotate to issue a new client token. Revoking the only valid client token suspends the fleet this way.
The install token cannot be revoked. If an install artifact leaks, revoke its Quick Deploy URL from the Deployment Tokens tab, and re-create the fleet if the token itself is exposed.
Quick Deploy URLs can be revoked individually from the Deployment Tokens tab.
Kubernetes fleet tokens
A Kubernetes fleet has one client token, created with the fleet and embedded in the bridge's install bundle when the bundle is generated. There is no expiry choice at creation, and the raw token can be copied from the Client 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 artifacts, tokens, and Quick Deploy URLs out of source control and shared documents. They are credentials.
- 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