Quickstart

You need an xPlant workspace on xPlant+ Teams or Enterprise (compare plans), which include the whole API (Hobby and Pro Lab keys can connect devices only), and a role of member or above to grant the scopes below.

1. Create a keyCopy Anchor Link

1. In xPlant, open Settings → Integrations → API Keys.
2. Create a key, give it a name you'll recognise later (for example "Quickstart"), and tick Read workspace, Read plants and Read tasks.
3. Copy the key. It starts with xpk_live_ or xpk_dev_, and it's shown only once.

Store it in an environment variable rather than in code:

export XPLANT_API_KEY="xpk_live_…"

2. Check the keyCopy Anchor Link

GET /me tells you who the key is, which scopes it holds, and which it can use right now (effectiveScopes, after your role and plan). It needs no scope, so it's the safest first call.

curl https://app.xplantpro.com/api/v1/me \
  -H "Authorization: Bearer $XPLANT_API_KEY"

You should see:

{
  "ok": true,
  "data": {
    "key": { "name": "Quickstart", "prefix": "xpk_live_abcd", "status": "active" },
    "scopes": ["read:workspace", "read:plants", "read:tasks"],
    "effectiveScopes": ["read:workspace", "read:plants", "read:tasks"],
    "role": "member",
    "apiAccess": "full",
    "workspace": { "id": "…" },
    "user": { "id": "…" }
  }
}

If you get 401 UNAUTHORIZED, the key is wrong or has been revoked. If you get 402 PAID_PLAN_REQUIRED, your workspace's plan doesn't include this call; see Plans and access.

3. Read some dataCopy Anchor Link

List the first page of plants:

curl "https://app.xplantpro.com/api/v1/plants?limit=5" \
  -H "Authorization: Bearer $XPLANT_API_KEY"

Every response has the same shape: ok, data, and on failure error and code. Read Requests and responses once and you know how every endpoint behaves.

4. See a scope error on purposeCopy Anchor Link

Your key has no write:tasks scope, so creating a task fails, and the error tells you exactly what's missing:

curl -X POST https://app.xplantpro.com/api/v1/tasks \
  -H "Authorization: Bearer $XPLANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Check the Alocasia line"}'

{ "ok": false, "data": null, "error": "Missing scope: write:tasks", "code": "FORBIDDEN" }

Branch on code (FORBIDDEN), not on the message. A key's scopes are fixed when it's created, so when an integration needs another scope, create a key that has it, switch over, and revoke the old one.

Next stepsCopy Anchor Link