Skip to main content

Enrollment Tokens

Enrollment Tokens are single-use or limited-use credentials that authorize an agent to enroll with the Sielum server and receive a device certificate. They replace the need to copy private keys to endpoints.

How it works​

When an agent runs sielum-agent enroll --token <token>, the server:

  1. Validates the token (checks it is active, not expired, and has remaining uses)
  2. Signs a device certificate for the enrolling endpoint (ECDSA P-256)
  3. Returns the signed certificate and the CA certificate
  4. Decrements the token's remaining use count (or marks it as consumed if max usage is reached)

The agent then stores the certificate locally and uses it for all subsequent gRPC connections.

Creating an Enrollment Token​

  1. Open the Dashboard and navigate to Settings → Enrollment Tokens
  2. Click New Token
  3. Configure the token:
    • Label — a name to identify where this token is used (e.g. "Linux rollout June 2026")
    • Max uses — maximum number of endpoints that can enroll with this token (leave blank for unlimited)
    • Expires at — optional expiry date after which the token is rejected
  4. Click Create — the token is shown once; copy it immediately

Using a Token during Enrollment​

Pass the token with the --token flag:

sudo ./sielum-agent enroll \
  --server         https://your-sielum-server.example.com \
  --token          "$ENROLLMENT_TOKEN" \
  --ca-fingerprint "$CA_FINGERPRINT" \
  --cert-dir       /etc/sielum/

See Agent Installation → for full enrollment examples.

Token lifecycle​

StateMeaning
ActiveToken is valid and can be used
ExpiredExpiry date has passed — no new enrollments
ExhaustedMax uses reached — no new enrollments
RevokedManually revoked in the dashboard

Enrolled agents with existing certificates are not affected when a token is revoked or expires — revocation only prevents new enrollments using that token.

Mass deployment​

For rolling out the agent across many endpoints, create a single token with a high max-use count (or unlimited) and distribute it via your configuration management tool (Ansible, Puppet, Chef) or MDM system. Once all endpoints are enrolled, revoke the token to prevent further use.