xPlantAPI

Scopes

What each of the 34 scopes allows, and the endpoints it unlocks.

Open in ChatGPTOpen in ClaudeView .md

A key carries exactly the scopes you choose when you create it in Settings → Integrations → API Keys. There is no default set, and no scope implies another: write:tasks does not grant read:tasks.

Scopes are fixed when a key is created. To change what an integration can do, create a new key with the scopes it needs, move the integration to it, then revoke the old key.

A key never does more than its owner can in xPlant. Each scope also needs a minimum role from the key's owner and a plan that includes it (both shown below). Above the owner's role, a call answers 403 FORBIDDEN; outside the plan, 402 PAID_PLAN_REQUIRED. GET /me lists the key's effectiveScopes: what it can use right now. See Plans and access.

Scope names follow <read|write>:<resource>. Grant each integration only what it calls.

A request without the scope it needs gets 403 FORBIDDEN, and the message names the missing scope, for example Missing scope: write:tasks. To see what a key holds before you call anything, use GET /me; it needs no scope.

Device tokens (xpd_) don't carry scopes. They can only write readings, heartbeats and events for their own device. See Device tokens.

Common setups

IntegrationScopes
Read-only dashboardread:workspace, read:plants, read:explants, read:sensor_readings
Task sync from your schedulerread:tasks, write:tasks, write:demand
Bench station running SOPsread:sops, write:sop_runs, read:sop_runs, write:sop_steps, read:labels, write:label_scans
Transfer and stage loggingread:plants, read:explants, read:transfers, write:transfers
Device provisioning (run once, off the device)read:devices, write:devices
Mirror change history into your warehouseread:events, read:plants, read:explants

All scopes

Workspace

ScopeAllowsMinimum rolePlansEndpoints
read:workspaceRead workspace and lab settingsAny memberTeams, EnterpriseGET /workspaces

Plants

ScopeAllowsMinimum rolePlansEndpoints
read:plantsRead plant recordsAny memberTeams, EnterpriseGET /plants
GET /plants/{id}
write:plantsCreate and update plant recordsmemberTeams, EnterprisePOST /plants
PATCH /plants/{id}

Explants

ScopeAllowsMinimum rolePlansEndpoints
read:explantsRead explant recordsAny memberTeams, EnterpriseGET /explants
GET /explants/{id}
write:explantsCreate and update explant recordsmemberTeams, EnterprisePOST /explants
PATCH /explants/{id}

Contaminations

ScopeAllowsMinimum rolePlansEndpoints
read:contaminationsRead contamination logsAny memberTeams, EnterpriseGET /contaminations
GET /contaminations/{id}
write:contaminationsSubmit contamination observationsmemberTeams, EnterprisePOST /contaminations

Tasks

ScopeAllowsMinimum rolePlansEndpoints
read:tasksRead scheduled tasks and due workAny memberTeams, EnterpriseGET /tasks
GET /tasks/{id}
GET /tasks/demand
write:tasksCreate, update, complete, and reopen tasksmemberTeams, EnterprisePOST /tasks
PATCH /tasks/{id}
write:demandPush sales/order demand numbers per genus for task prioritizationmanagerTeams, EnterprisePOST /tasks/demand

Comments

ScopeAllowsMinimum rolePlansEndpoints
read:commentsRead notes and comments on lab recordsAny memberTeams, EnterpriseGET /comments
write:commentsAdd notes and comments to lab recordsmemberTeams, EnterprisePOST /comments

Media

ScopeAllowsMinimum rolePlansEndpoints
read:assetsRead photos and media attached to lab recordsAny memberTeams, EnterpriseGET /assets
GET /assets/{id}
write:assetsAttach photos and media to lab recordsmemberTeams, EnterprisePOST /assets
read:media_recipesRead media recipe dataAny memberTeams, EnterpriseGET /media-recipes
GET /media-recipes/{id}
write:media_recipesCreate and update media recipesmemberTeams, EnterprisePOST /media-recipes
PATCH /media-recipes/{id}

Transfers

ScopeAllowsMinimum rolePlansEndpoints
read:transfersRead transfer and stage history for plants and explantsAny memberTeams, EnterpriseGET /stages
GET /transfers
write:transfersRecord transfers and advance the stage of plants and explantsmemberTeams, EnterprisePOST /stages
POST /transfers

SOPs

ScopeAllowsMinimum rolePlansEndpoints
read:sopsRead SOP templates and stepsAny memberTeams, EnterpriseGET /sops
GET /sops/{id}
read:sop_runsRead SOP execution history: who ran which step, whenAny memberTeams, EnterpriseGET /sop-runs/{id}
write:sop_runsCreate and advance SOP run sessionsmemberTeams, EnterprisePOST /sop-runs
write:sop_stepsPost confirmations, scans and measurements against a step of an SOP runmemberTeams, EnterprisePOST /sop-runs/{id}/steps/{stepId}/events
POST /sop-runs/{id}/steps/{stepId}/measurements

Labels

ScopeAllowsMinimum rolePlansEndpoints
read:labelsResolve QR/barcode label codes to entity recordsAny memberTeams, EnterpriseGET /labels/resolve
write:label_scansSubmit label scan eventsmemberTeams, EnterprisePOST /label-scans

Devices

ScopeAllowsMinimum rolePlansEndpoints
read:devicesList registered devices and their statusAny memberAll paid plansGET /devices
GET /devices/{deviceId}/tokens
write:devicesRegister devices, send heartbeats, and manage device tokensmemberAll paid plansPOST /devices
POST /devices/{deviceId}/heartbeat
POST /devices/{deviceId}/tokens
DELETE /devices/{deviceId}/tokens/{tokenId}
read:sensor_readingsQuery historical sensor readingsAny memberTeams, EnterpriseGET /sensor-readings
write:sensor_readingsSubmit environmental sensor readings (temperature, humidity, etc.)memberAll paid plansPOST /sensor-readings
write:device_eventsSubmit device status eventsmemberAll paid plansPOST /device-events

Equipment

ScopeAllowsMinimum rolePlansEndpoints
read:equipmentRead the lab equipment library and its maintenance historyAny memberTeams, EnterpriseGET /equipment
GET /equipment/{id}
GET /equipment/{id}/events
write:equipment_eventsRecord that a piece of equipment was used, calibrated, serviced or faultedmemberTeams, EnterprisePOST /equipment/{id}/events

Commercial

ScopeAllowsMinimum rolePlansEndpoints
read:pricingRead culture line prices, pricing tiers, and price historymanagerTeams, EnterpriseGET /pricing/culture-lines
GET /pricing/events
read:commerceRead store order lines and sell-through summariesmanagerTeams, EnterpriseGET /commerce/order-lines
GET /commerce/sell-through

History

ScopeAllowsMinimum rolePlansEndpoints
read:eventsRead plant and explant edit history (audit events)Any memberTeams, EnterpriseGET /events

No scope needed

Edit on GitHub

Authentication and API keys

How to create a key, send it, keep it safe, and tell the two kinds of credential apart.

Device tokens

Give each device an xpd_ token that can post its own readings and nothing else. Never put a workspace key on a device.

On this page

Common setupsAll scopesWorkspacePlantsExplantsContaminationsTasksCommentsMediaTransfersSOPsLabelsDevicesEquipmentCommercialHistoryNo scope needed