Enrollment

Enrollment Flow

Agent                                 API Server
  │                                      │
  │─── POST /api/v1/agents/enroll ──────►│
  │    { hostname, os, arch,             │
  │      enrollmentSecret, siteId }      │
  │                                      │
  │    Validate enrollment secret        │
  │    Create device record              │
  │    Generate brz_ token               │
  │    Hash token (SHA-256) → store      │
  │    Issue mTLS cert (if configured)   │
  │                                      │
  │◄── 201 { agentToken, deviceId,  ─────│
  │         orgId, siteId, mtls? }       │
  │                                      │
  │    Store config to disk              │
  │    Connect WebSocket                 │
  │                                      │
  │─── WS /agents/:id/ws ──────────────►│
  │    Authorization: Bearer brz_...     │
  │                                      │
  │◄── { type: "connected" } ────────────│
  │                                      │
  │─── { type: "heartbeat", ... } ──────►│
  │                                      │

Token Security

Agent tokens follow the brz_ prefix convention:

• Generation: Cryptographically random, 32-byte hex string with brz_ prefix
• Storage (server): Only the SHA-256 hash is stored in the agentTokenHash column
• Storage (agent): The raw token is stored in secrets.yaml with 0600 permissions (the main agent.yaml config uses 0640 so the Helper can read it)
• Validation: API hashes incoming tokens and compares against stored hash
• Same pattern as API keys (apiKeyAuth.ts)

Note

The agentTokenHash column is nullable to support migration of pre-existing devices. New enrollments always populate the hash.

Enrollment Keys

Enrollment keys are created in the dashboard and can be scoped to:

• Organization — devices enroll into a specific org
• Site — devices enroll into a specific site within an org
• Expiry — keys expire after a configurable TTL (default: 60 minutes)
• Usage limit — keys can be limited to a number of uses

Bulk Enrollment

For deploying agents at scale:

# Environment variable method (for scripts/GPO/MDM)
export BREEZE_SERVER_URL=https://breeze.yourdomain.com
export BREEZE_AGENT_ENROLLMENT_SECRET=your-secret

breeze-agent enroll YOUR_ENROLLMENT_KEY

The enrollment key is a required positional argument. The site is determined by the enrollment key on the server side. The agent reads BREEZE_SERVER_URL and BREEZE_AGENT_ENROLLMENT_SECRET from environment variables when flags aren’t provided.

Re-enrollment

If an agent’s token is compromised or the device needs to be reassigned:

1. Revoke the device in the dashboard (invalidates the token hash)
2. Delete the config on the device:
   • Linux: sudo rm /etc/breeze/agent.yaml /etc/breeze/secrets.yaml
   • macOS: sudo rm "/Library/Application Support/Breeze/agent.yaml" "/Library/Application Support/Breeze/secrets.yaml"
   • Windows: Remove-Item C:\ProgramData\Breeze\agent.yaml, C:\ProgramData\Breeze\secrets.yaml
3. Re-enroll: sudo breeze-agent enroll YOUR_ENROLLMENT_KEY --server ... --enrollment-secret ...

Reusing a hostname for a decommissioned device

When a device row is decommissioned in the dashboard, the original device id is retired but the hostname is free to be claimed again. Running breeze-agent enroll from a new install on the same hostname creates a fresh device record (new id, new token) rather than failing with a hostname collision. The decommissioned row stays in audit history for compliance — the new device is treated as a distinct asset from day one.

The only exception is if the decommissioned device’s token was suspended for a security reason (for example, a cross-tenant access probe). In that case re-enrollment is blocked with a 409 Conflict until an administrator reviews the previous incident. The response includes the reason so the technician on-site knows to escalate rather than retry.