Token & Enrollment Lifecycle

Two distinct objects govern the agent's lifecycle: the deployment token (a reusable secret you distribute) and the enrollment (a single device that has joined). Keeping them straight is the key to understanding both deployment and revocation.

Deployment tokens

A deployment token is a reusable, capped enrollment secret.

• Generation — created in Agents > Generate deployment token. The plaintext value is shown once; store it only in MDM managed configuration.
• Enrollment cap — the maximum number of devices that may enroll with the token. Enrollment is blocked once the cap is reached.
• Expiry (optional) — a token can be persistent or time-bounded. Expiry only blocks new enrollments; your existing fleet is unaffected.
• Mode — tokens are typically issued for MDM deployment.

Enrollment

When a device runs the agent for the first time and presents a valid deployment token:

1. The device enrolls and is counted against the token's cap.
2. It receives its own rotating credential. The shared deployment token is never reused for ongoing heartbeats — each device authenticates with its individual credential thereafter.
3. The device appears in the enrollment table and begins reporting posture, agent version, and update state.

This separation is deliberate: compromising or retiring a deployment token does not expose already-enrolled devices, and vice-versa.

Rotation and lineage

Rotating a token mints a child token that supersedes its parent, forming a lineage chain:

• The parent is revoked; the child carries forward as the active token.
• Lineage is preserved so you can trace which token descended from which.
• Rotate when you want to refresh the distributed secret without disrupting enrolled devices — existing devices keep their own credentials.

Token vs. enrollment at a glance

Action	Affects future enrollments	Affects already-enrolled devices
Revoke / expire a token	✅ blocked	❌ unaffected
Rotate a token	✅ parent retired, child active	❌ unaffected
Revoke a token lineage	✅ token + all descendants blocked	❌ unaffected — revoke devices individually
Revoke an enrollment	❌	✅ that device detached

For the full mechanics of each revoke path, see Revoke Semantics.