> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charlemagnelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrollment

> API endpoints for device enrollment codes and enrollment keys

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "count": 1
}
```

#### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

### Response

```json theme={null}
{
  "device_id": "dev_01hx...",
  "org_id": "org_01hx..."
}
```

### Errors

| Code  | Description                                   |
| ----- | --------------------------------------------- |
| `401` | Missing or invalid enrollment key             |
| `400` | Invalid or expired enrollment code            |
| `409` | Machine ID is already enrolled in another org |