Create a device token
Creates a credential for one device. Put it on the device in place of a workspace key: it can send that device's heartbeats, readings and events, and nothing else.
https://app.xplantpro.com/write:devicesThe secret is in token, and this is the only response that contains it. Store it on the device straight away. If it is lost, mint another and revoke the old one.
Mint tokens with a workspace key — a device token cannot create tokens. A retried request mints a second token rather than returning the first, so revoke whichever one you do not keep. Every field is optional; send {} or no body at all.
See also: Device tokens.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
deviceId | string (uuid) | Yes | The device's id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | A label to tell the device's tokens apart, for example Grow room Pi. 1–120 characters. |
environment | "production" | "development" | No | production mints an xpd_live_ token and development an xpd_dev_ one. Both act on the same workspace. Default "production". |
Example
curl -X POST https://app.xplantpro.com/api/v1/devices/5f7a9c1e-3b5d-4f7a-9c1e-3b5d7f9a1c3e/tokens \
-H "Authorization: Bearer $XPLANT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Grow room Pi"
}'Response
201 with { "ok": true, "data": … }. data holds the result.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | — |
deviceId | string (uuid) | Yes | The device the token belongs to. |
name | string | null | Yes | The label it was given when it was minted. |
prefix | string | Yes | The first characters of the token — enough to recognise it, never enough to use it. |
token | string | Yes | The secret. Returned in this response only — store it on the device now, because it cannot be shown again. |
createdAt | string | Yes | When the token was minted. |
{
"ok": true,
"data": {
"id": "4f8a2c6e-9d1b-4e7a-b3c5-6a0d8f2e4b19",
"deviceId": "8e3b1f52-6c0d-4a7e-9b21-5f4d8c2a7e13",
"name": "Grow room Pi",
"prefix": "xpd_live_0123456789a",
"token": "xpd_live_0123456789abcdef0123456789abcdef0123456789abcdef",
"createdAt": "2026-09-01T09:40:00.000Z"
}
}| Response header | Meaning |
|---|---|
X-Request-Id | Identifies this request. Include it when you contact support. |
Errors
| Status | Code | When |
|---|---|---|
401 | UNAUTHORIZED | The key is missing, malformed or revoked, or its owner is no longer a member of the workspace. |
402 | PAID_PLAN_REQUIRED | The workspace has no paid plan. Connecting devices is included with every paid plan. |
403 | FORBIDDEN | The key lacks a scope this operation requires, or its owner's current role in the workspace cannot use it — a key never does more than its owner can in xPlant. error names the scope, and for a role, the role it needs. |
403 | DEVICE_TOKEN_NOT_ACCEPTED | A device token was sent; this operation needs a workspace API key. |
404 | NOT_FOUND | No device with this id is registered in the key's workspace. |
422 | VALIDATION_ERROR | A field failed validation, such as a name longer than 120 characters. error names it. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | DEVICE_TOKEN_CREATE_FAILED | The token could not be created, and none was minted. Retry. |
Branch on code, never on the error text. See Errors.
List device tokens
Every token minted for the device, active and revoked, newest first. Each carries its prefix, name, status and last use — what you need to tell tokens apart and decide which to revoke. The secret itself is never returned after the token is minted.
Revoke a device token
Stops one device token working: the next request made with it is refused as unauthorized. The token stays in the device's token list, marked revoked with the time it was revoked, so the list remains a complete history of the device's credentials.