Enrollment

A fresh robot has no Roboflare 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 hash is stored server-side; the raw key value is returned exactly once at creation and never again.

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 — store it now or lose it.

Using an enrollment key

The Rust agent reads enrollment_key from ~/.roboflare/config.toml and posts it on first connect. 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.

Subsequent connects use the robot token directly. The enrollment key can be deleted from the robot's config at that point.

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.