# Redeem Device Enrollment

> Redeem an enrollment token, registering this machine as the bot's device.

Canonical URL: https://docs.botyard.io/docs/api/device-enrollment/redeem_device_enrollment_v1_public_device_enrollment_redeem_post

`POST /v1/public/device-enrollment/redeem`

Redeem an enrollment token, registering this machine as the bot's device.

Registering the public key and consuming the token are atomic: the token
is spent by a conditional UPDATE that exactly one concurrent caller can
win, and the device row is written in the same transaction, so a token is
never consumed without producing the device it paid for.

No session, assertion or SVID is issued here. The device credential buys
only the right to *ask* for one, on every future connection, against a
registry that can deny it immediately.

*** THERE IS EXACTLY ONE WAY TO LEAVE HERE WITHOUT A DEVICE ROW, AND IT IS
AN ERROR. *** A 2xx from this endpoint means the registry holds a live,
active device for the caller — either written by this call (``201``,
``newly_enrolled``) or read back within it (``200``, the machine already
being that device and offering its key). The caller may therefore treat
"this call succeeded" as "a device exists server-side", which is the
property an installer needs and the one it cannot establish for itself.

## Request body

`application/json`: DeviceEnrollmentRequest (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The plaintext enrollment token |
| `public_key` | string | yes | Base64url-encoded SPKI of the device's P-256 public key (ES256). Long-lived and never rotated |
| `label` | string \| null | no | Machine label, typically the hostname |
| `custody_tier` | BotDeviceCustodyTier | yes | Where this device keeps its private key. SELF-DECLARED: the platform records it and never verifies it, and it is never an input to an authorization decision |
| `effect_coverage` | BotDeviceEffectCoverage | no | How much of this runtime's activity the platform mediates |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | Successful Response | DeviceEnrollmentResponse |
| `default` | RFC 9457 Problem Details error response | ProblemDetails |

Full schemas: operation `redeem_device_enrollment_v1_public_device_enrollment_redeem_post` in the OpenAPI spec at https://api.botyard.io/openapi.json.