---
method: POST
path: /api/devices/claim
auth: jwt
area: devices
---
<!-- source: internal/handlers/devices.go DeviceHandler.ClaimDevice -->

# Claim Device (Pairing Code)

Bind a pending device registration to the CALLER's account by entering the
6-digit pairing code shown on the registering device's screen. This is the
web-side replacement for the retired broadcast-list approve: unclaimed
registrations appear in no account's pending list, and only whoever reads the
code — the person holding the device — can claim it.

**Endpoint**: `POST /api/devices/claim`
**Auth**: JWT
**Content-Type**: `application/json`

The code is normalized before matching: spaces and dashes typed around the
digits ("583 912") are stripped. Lookups and claims share a per-account rate
limit (12 attempts/minute).

## Request Body

| Field        | Type   | Required | Description                                  |
| ------------ | ------ | -------- | -------------------------------------------- |
| pairing_code | string | Yes      | The 6-digit code shown on the device's screen |

### Example Request

```json example-request
{
  "pairing_code": "583912"
}
```

## Response (200 OK)

```json example-response
{
  "message": "device paired successfully",
  "device_name": "My Kindle Paperwhite",
  "device_type": "koreader",
  "approved": true
}
```

HTMX callers (the Devices page confirm button) receive `HX-Refresh` instead of
a JSON body. On success the registering device's status poll returns the fresh
`auth_token` and sync endpoints, exactly as in the old approve flow.

## Error Responses

| Code | Description                                            |
| ---- | ------------------------------------------------------ |
| 400  | Invalid pairing code (generic — never confirms whether a registration exists) |
| 409  | Pairing code already used, or the device identifier is registered to another user |
| 410  | Pairing code expired                                   |
| 429  | Too many pairing attempts                              |

## Related

- `POST /api/devices/claim/lookup` — the confirm card's data, without binding
- `POST /api/devices/register` — starts the registration and mints the code