Skip to content

Native Agent Enrollment

Enrollment exchanges a one-time, expiring token for a long-lived, per-node revocable credential.

Flow

Admin (panel)                                Agent (new node)
POST /hypervisors/{uuid}/enrollment-token
  → generate one-time token (raw shown ONCE)
  ← 201 { token, expires_at }
      │
      └──── out-of-band (provisioning system) ────►
                                      pterocloud-agent enroll --panel <url> --token <token>
                                      POST /api/pterocloud/agent/enroll
                                        → validate token (single-use, unexpired)
                                        → burn token, issue credential
                                      ← 201 { credential_id, secret }  (ONCE)

Generate a token

Generate an enrollment token from the admin API for a pending hypervisor:

curl -X POST "$PANEL/api/application/pterocloud/hypervisors/{uuid}/enrollment-token" \
    -H "Authorization: Bearer $APP_API_KEY"

The response contains the raw token and its expiry. It is shown once, stored only as a SHA-256 hash, and never logged.

Enrollment token is a credential

Deliver it out of band and treat it like a password. This documentation uses the placeholder pct_reg_XXXX…. Never screenshot or paste a real token.

Enroll the host

pterocloud-agent enroll --panel https://panel.example.com --token pct_reg_XXXX…

On success the agent writes its credential file (0600) and begins sending heartbeats.

Rules

  • Enrollment tokens are single-use and expire (default one hour).
  • A burned token presented again is logged as cloud:agent.enrollment_token_reused and rejected.
  • A revoked or expired token is rejected with the matching PC-AGT-### code.
  • Enrollment is rate-limited per IP.

Revocation

Revoke all live credentials for a hypervisor:

curl -X POST "$PANEL/api/application/pterocloud/hypervisors/{uuid}/revoke-agent" \
    -H "Authorization: Bearer $APP_API_KEY"

Revoking an agent never stops VMs. To re-enroll, generate a new token and enroll again.

Authentication of every call

Each authenticated agent call presents Authorization: Bearer {credential_id}.{secret}. Malformed, revoked or unverifiable credentials are rejected; a known-but-revoked credential is distinguished from an unknown one so operators can tell a decommissioned node from an attack. The protocol version header must be within the accepted range. Rate limits answer 429 with Retry-After.