Enrollment failures

Overview

Enrollment is the one-time exchange of a random, single-use, short-lived enrollment token for a permanent collector credential. AssurIQ never stores the token itself, only its SHA-256 hash, so a failed exchange cannot be diagnosed by looking the token up directly — the error code returned during install tells you which of four things went wrong.

AIQ-ENR-001 — Token invalid or already used

Enrollment tokens are single-use. Once a collector has exchanged a token for a credential, that token can never be used again, even by the same host.

• Confirm the token was copied in full, with no truncation or extra whitespace.
• Confirm no earlier install attempt already succeeded with this token — check the site's Collectors panel for an unexpected new entry.
• Generate a fresh token and retry.

AIQ-ENR-002 — Token expired

Tokens are short-lived by design. If too much time passed between generating the token and running the install command, the exchange is rejected.

• Generate the token immediately before running the install command, not in advance.
• If distributing install instructions to a technician for later use, have them generate their own token at install time instead of reusing a pre-issued one.

AIQ-ENR-003 — Token revoked

A token can be revoked from AssurIQ before it is used, for example if it was generated in error or pasted somewhere it should not have been.

• Check the site's Collectors panel for a revocation record matching the token's issue time.
• Generate a new token; revocation is final and cannot be undone.

AIQ-ENR-004 — Control plane unreachable

The token itself may be valid, but the host could not complete the outbound HTTPS/mTLS handshake to the control plane at all.

curl -v https://<control-plane-url>/healthz

• Confirm outbound 443 is allowed and not intercepted by TLS inspection.
• Confirm DNS resolves the control plane hostname.
• If a proxy is required at this site, configure it before retrying enrollment.

• Firewall and egress requirements
  The collector is outbound-only. What to allow, on which ports, and why no inbound rules are ever needed.
• Proxy configuration
  Route collector traffic through an explicit or PAC-defined proxy without breaking mTLS.

After a fix

Re-run the install/enroll command with a freshly generated token. A successful exchange moves the collector from Enrollment Pending to Healthy within about 60 seconds of the first heartbeat.

• AIQ-ENR-001Enrollment token invalid or already used
  The enrollment token was not recognized, or has already been exchanged for a credential.
• AIQ-ENR-002Enrollment token expired
  Too much time passed between generating the token and completing enrollment.
• AIQ-ENR-003Enrollment token revoked
  The token was revoked before it was used.
• AIQ-ENR-004Control plane unreachable during enrollment
  The host could not complete the outbound HTTPS/mTLS handshake to the control plane.