Enrollment

A fresh robot has no Beacon identity. Enrollment is the one-time exchange that gives it one.

The two tokens

Enrollment keys are multi-use (default max_uses: 100) and time-bounded (default expires_in_hours: 24). The server stores both the SHA-256 hash used for lookup and the raw rf_enroll_<hex> value for operators who need to retrieve it later.

Robot tokens are minted at first successful enrollment and persisted on the robot alongside its config. The server only ever sees the hash.

Creating an enrollment key

POST /api/enrollment-keys
{
  "site_id":         "...",
  "fleet_id":        "...",
  "name":            "warehouse-a-batch-1",
  "max_uses":        50,
  "expires_in_hours": 48
}

The fleet_id must belong to the site_id. The response includes the raw key value, and later list responses include key_value.

Using an enrollment key

An agent posts the key on first connect:

beacon agent run --enrollment-key rf_enroll_<hex> --name warehouse-bot-01

The control plane:

1. Looks up the key by SHA-256 hash.
2. Rejects if revoked, expired, or uses >= max_uses.
3. Mints a robot token, increments uses, and inserts the robots row bound to the key's site and fleet.
4. Returns the token to the agent, which persists it to ~/.config/roboflare/agent.toml (or the standalone agent's config path).

Subsequent runs use the saved robot token directly; the enrollment key is no longer needed on that machine.

Listing and revoking keys

GET  /api/enrollment-keys
POST /api/enrollment-keys/{id}/revoke

Revoking sets revoked_at and rejects future claims. Robots already enrolled with the key are unaffected — they have their own token.

Why not just hand out robot tokens directly

Robot tokens are long-lived and bound to one device. Distributing them through your CI/provisioning system would mean cataloguing per-robot secrets before the robots exist. Enrollment keys let you pre-stage one secret for a whole batch and let the agent generate its own token on first boot.