Enrollment

Enrollment connects an agent running in your network to your xgress3 account. It is a shared process: the agent starts enrollment and an operator approves the code in the console.

Flow overview

Step by step

1. Agent starts enrollment

When no valid certificate exists, the agent calls the regional platform:

POST https://{region}.xg3.io/enroll

It receives an agent ID, an enrollment code (display form XXXX-XXXX), an expiry time, and an enrollment secret stored locally in pending-enrollment.json.

The agent displays the code in its interactive console UI (Windows CLI) or logs it at warning level when --no-interactive is set (Windows service). When you use the one-line install script, the installer prints the code in PowerShell after the service starts. Give this code to someone who can access the console.

2. Operator approves in the console

1. Select the correct account and region in the console header.
2. Open Agents → Enroll Agent.
3. Enter the code and click Approve.

The agent does not appear in your agent list until approval succeeds.

3. Agent completes automatically

After approval the agent:

1. Polls GET /enroll/status?agent_id=… until status is approved
2. Submits a certificate signing request via POST /csr
3. Saves the issued certificate to the data directory
4. Removes pending-enrollment.json
5. Opens the tunnel

Until the tunnel is up, HTTP ingress to services using this agent will fail with an agent-unavailable style error.

Enrollment code expiry

Codes are short-lived. Approve before expiry.

While waiting for approval, the agent polls enrollment status using a one-time enrollment secret returned at enroll time (sent as the X-Xg3-Enrollment-Secret header). Status checks without a valid secret always report expired. Upgrade the agent if enrollment polling fails after a platform update.

If a code expires while the agent is still running, the agent discards its pending enrollment state and starts a new enrollment automatically. Watch the agent console or log file for a new code and approve the latest one.

Resume after restart

If agent-cert.der, agent-key.pem, and agent-cert-expiry.txt exist and the certificate is valid, the agent skips enrollment and opens the tunnel immediately using the stored certificate.

Region must match

The agent’s region is fixed at enrollment. The operator must approve in the same region selected in the console header. A region mismatch causes approval or ingress failures.

Pairing checklist

Check	Reason
Same region in console header and agent --region	Enrollment and ingress are region-scoped
Code approved before expiry	Expired codes are rejected
Outbound HTTPS to gateway allowed	Enrollment and tunnel use the gateway URL
Operator has enroll permission	Enroll Agent must be available in the console

See Agents and services for the console side of enrollment.