Skip to main content

​
Enrollment Key

The enrollment key is a long-lived API key used by Agent Charley during device registration. It is separate from user JWTs.

​
Get Enrollment Key

GET /api/enrollment-key

​
Response

{
  "key": "ek_live_...",
  "created_at": "2025-09-01T00:00:00Z"
}

​
Rotate Enrollment Key

Generates a new enrollment key and invalidates the previous one. 
POST /api/enrollment-key

​
Response

{
  "key": "ek_live_...",
  "created_at": "2025-10-14T00:00:00Z"
}

​
Revoke Enrollment Key

Deletes the enrollment key entirely. New device enrollments are blocked until a new key is generated. 
DELETE /api/enrollment-key

​
Response

204 No Content

​
Enrollment Codes

One-time codes used to enroll specific devices. Codes expire after 24 hours.

​
Generate Enrollment Code(s)

POST /api/enrollment-codes

​
Request Body

{
  "count": 1
}

​
Response

{
  "codes": [
    {
      "code": "ABCD-1234",
      "expires_at": "2025-10-15T18:00:00Z"
    }
  ]
}

​
Generate and Email a Code

Generates a single code and sends it to the specified email address with installation instructions. 
POST /api/enrollment-codes/email

​
Request Body

{
  "email": "bob@acme.com"
}

​
Response

200 OK

​
Device Enrollment (Agent)

Called by Agent Charley during the charley enroll command. Uses the enrollment key for authentication (not a user JWT). 
POST /api/device/enroll

​
Request Headers

X-Enrollment-Key: ek_live_...

​
Request Body

{
  "code": "ABCD-1234",
  "machine_id": "<unique-hardware-id>",
  "hostname": "alice-macbook-pro",
  "metadata": {
    "os": "macOS 14.5",
    "arch": "arm64"
  }
}

​
Response

{
  "device_id": "dev_01hx...",
  "org_id": "org_01hx..."
}

​
Errors

CodeDescription
401Missing or invalid enrollment key
400Invalid or expired enrollment code
409Machine ID is already enrolled in another org