Device tokens

A device token (xpd_…) is a credential for one registered device. It can post that device's sensor readings, events and heartbeats, and it is refused everywhere else. A workspace key (xpk_…) can read your plants, explants and tasks; a device token can't read anything.

What a device token can doCopy Anchor Link

A device token is accepted on exactly these endpoints, and only for its own device:

• POST /device-events: Record a device event
• POST /devices/{deviceId}/heartbeat: Send a heartbeat
• POST /sensor-readings: Submit sensor readings

Anything else answers 403 DEVICE_TOKEN_NOT_ACCEPTED. Writing about a different device (another device_id, even one entry inside a batch) answers 403 DEVICE_TOKEN_WRONG_DEVICE and rejects the whole request.

Device tokens don't carry scopes; what they can do is fixed. Each token is rate limited like a key (1,000 requests per minute), and its traffic also counts toward your workspace's shared limit. See Rate limits.

Setting up a deviceCopy Anchor Link

Do this once, from a machine you control, with a workspace key that has write:devices (and read:devices if you want to list tokens later).

1. Register the deviceCopy Anchor Link

curl -X POST https://app.xplantpro.com/api/v1/devices \
  -H "Authorization: Bearer $XPLANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Grow room Pi", "type": "gateway", "hardware": "Raspberry Pi 4B"}'

Keep the device's id.

2. Create its tokenCopy Anchor Link

curl -X POST "https://app.xplantpro.com/api/v1/devices/$DEVICE_ID/tokens" \
  -H "Authorization: Bearer $XPLANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Grow room Pi"}'

{ "ok": true, "data": { "token": "xpd_live_…", "prefix": "xpd_live_9f3a" } }

The token is returned once and never again. Put it on the device now (in its config file or secrets store, not in code you commit). Listing a device's tokens later shows prefixes, status and last use, but never the secret.

3. Use it on the deviceCopy Anchor Link

curl -X POST https://app.xplantpro.com/api/v1/sensor-readings \
  -H "Authorization: Bearer $XPLANT_DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "'"$DEVICE_ID"'", "type": "temperature", "value": 23.4, "unit": "C"}'

One device or many?Copy Anchor Link

A gateway that reads several probes is usually one device posting several reading types (temperature, humidity, co2…) under its own device_id, with one token. That's the recommended setup.

If you want each probe to appear as its own device in xPlant (probes in different rooms, for example), register each probe and create a token per probe. The gateway then holds one token per device and uses the matching one for each probe's readings.

Losing or retiring a tokenCopy Anchor Link

• Lost or leaked a token? Create a new one for the same device, switch the device over, then revoke the old one. A revoked token is refused from its next request. List the device's tokens to find its id by prefix and last use.
• Taking a device out of service revokes all of its tokens in the same step, and so does deleting it. There's nothing extra to remember.