Sensor Enrollment Tokens

Enrollment tokens are the short-lived bootstrap credentials that allow a new sensor to trade proof of authorization for a long-lived mTLS client certificate. After enrollment is complete, the sensor authenticates entirely via that certificate and the token is no longer used.

The Telovix Console stores only the SHA-256 hash of each token. The plain token is returned once at creation and is never stored or retrievable again. Treat tokens like passwords: store them securely until the enrollment completes, then discard them.

Prerequisites

• Active Console session authenticated as a user with operator role or higher
• Console setup already complete (setup wizard finished, license imported, admin account created)

---

Token types

Two token types exist in the Console:

One-time token (once)

The default token type. Created when you click Deploy Sensor for a VM or bare-metal host.

• Valid for 15 minutes by default (configurable from Console Settings > Enrollment)
• Single use: consumed the first time it is presented during enrollment
• After use, the status field changes from pending to used
• Tokens that expire unused move to expired status
• A re-enrollment token is also a one-time token, but it is bound to a specific sensor_id so only that sensor can use it

Token format: tse_ followed by 32 bytes of random data encoded as URL-safe base64.

Cluster token (cluster)

Used for Kubernetes DaemonSet deployments and other fleet-scale rollouts.

• Reusable by all nodes in the named cluster
• Default TTL: 365 days (configurable up to 730 days via expires_days)
• Bound to a cluster_id; sensors that present a different cluster name during enrollment are rejected
• Optional max_nodes cap: enrollment is rejected after this many nodes have used the token
• Generated via the Deploy Sensor wizard (Kubernetes path)

---

Token status lifecycle

Status	Meaning
pending	Token exists and has not been used yet; may still be valid or expired
used	Token was consumed by a successful enrollment
expired	Token reached its expires_at without being used
revoked	Token was explicitly revoked before use

Active tokens are listed in the Console under Sensors > Enrollment Tokens. Tokens in used status appear briefly until the next cleanup cycle.

---

Create tokens from the Console

One-time token (VM / Bare Metal)

1. Go to Sensors and click Deploy Sensor
2. Select VM / Bare Metal
3. Enter a node name, select a node role, and select the sensor flavor
4. Click Generate Token

The wizard generates a ready-to-run install command with the token embedded. The token is valid for 15 minutes from generation.

If the Deploy Sensor button is greyed out or missing, the most common cause is the logged-in account not having operator or admin role; a viewer or analyst account cannot create enrollment tokens.

Deploy Sensor wizard showing the generated one-line install command with the enrollment token visible. Click to enlarge

Cluster token (Kubernetes)

1. Go to Sensors and click Deploy Sensor
2. Select Kubernetes
3. Enter a cluster name
4. Click Generate Cluster Token

The wizard generates the token and an example helm install command. Cluster tokens are valid for 365 days by default.

If the wizard shows a capacity_warning after generating the cluster token, the most common cause is the fleet approaching its license node limit; enrollment will be rejected once the limit is reached, so request a license upgrade from the Portal before deploying more nodes.

---

Automation and API access

Enrollment tokens can also be created, listed, and revoked programmatically using the v2 API with an API key scoped to sensors:read (listing) or sensors:write (create and revoke). See Enrollment token API in the API reference.

WARNING

Always use a re-enrollment token when updating credentials on an existing sensor. Using a plain enrollment token creates a new, separate sensor record instead of updating the existing one.

---

List tokens

In the Console, navigate to Sensors > Enrollment Tokens. Each token entry shows its status, label, expiry time, creation time, and used time if applicable. The plain token is not shown in listings.

Pending enrollment tokens also appear at the top of Sensors.

---

Auto-approve rules

Auto-approve rules let you pre-configure which cluster identities and node roles are automatically accepted at enrollment without per-enrollment operator approval. They are independent of tokens.

In the Console, navigate to Sensors > Auto-Approve Rules and click Create Rule.

Field	Required	Description
cluster_id	Yes	Cluster identifier this rule applies to
label	Yes	Human-readable label (max 128 chars)
allowed_roles	No	Node roles that are auto-approved (empty = all roles)
max_nodes	No	Cap on the number of auto-approved nodes for this cluster

Sensors > Auto-Approve Rules page showing the rule list with cluster ID, allowed roles, node cap, and delete button per rule. Click to enlarge

To delete a rule, click the delete icon next to it on the Auto-Approve Rules page. Deleting a rule does not affect already-enrolled sensors.

---

License capacity warnings

When creating a token, the response includes a capacity_warning field if the fleet is at or above 90% of the license node limit. The warning text specifies how many slots are remaining.

If the fleet is already at the license limit, token creation succeeds but sensor enrollment will fail with a NodeLimitExceeded error when the sensor attempts to enroll.

---

Security recommendations

• Keep bare-metal token TTLs as short as the deployment allows. 15 minutes is the default and is appropriate for most manual installs. Do not extend TTLs without a specific reason.
• Never bake tokens into machine images. A token in an image can be extracted from snapshot storage or backups and used to enroll unauthorized nodes.
• Scope cluster tokens to the smallest cluster identity that makes sense. A token scoped to ran-zone-a cannot be used to enroll nodes that claim a different cluster name.
• Use max_nodes on cluster tokens for any deployment where the expected node count is bounded. This limits the blast radius if the token is compromised.
• Rotate tokens on a schedule for long-lived DaemonSet deployments. Generate a new cluster token, update the Kubernetes Secret, and allow the init container credential-detection logic to re-enroll nodes on next restart.
• All token creation and use is recorded in the audit log with action types sensor_enrollment_token_created and sensor_enrolled. Revocations are also logged.

---

Further reading

• Sensor: VM / Bare Metal
• Sensor: Kubernetes (Helm)
• Sensor: Ephemeral / Cloud-Init
• mTLS and Certificates
• Audit Log