# Scopes

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

Source: https://docs.xplantpro.com/docs/scopes

A key carries exactly the scopes you choose when you create it in [Settings → Integrations → API Keys](https://app.xplantpro.com/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`](https://docs.xplantpro.com/docs/api/account/get-me.md) lists the key's `effectiveScopes`: what it can use right now. See [Plans and access](https://docs.xplantpro.com/docs/authentication.md#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`](https://docs.xplantpro.com/docs/api/account/get-me.md); 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](https://docs.xplantpro.com/docs/device-tokens.md).

## Common setups

| Integration | Scopes |
| --- | --- |
| Read-only dashboard | `read:workspace`, `read:plants`, `read:explants`, `read:sensor_readings` |
| Task sync from your scheduler | `read:tasks`, `write:tasks`, `write:demand` |
| Bench station running SOPs | `read:sops`, `write:sop_runs`, `read:sop_runs`, `write:sop_steps`, `read:labels`, `write:label_scans` |
| Transfer and stage logging | `read:plants`, `read:explants`, `read:transfers`, `write:transfers` |
| Device provisioning (run once, off the device) | `read:devices`, `write:devices` |
| Mirror change history into your warehouse | `read:events`, `read:plants`, `read:explants` |

## All scopes

### Workspace

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:workspace` | Read workspace and lab settings | Any member | Teams, Enterprise | [`GET /workspaces`](https://docs.xplantpro.com/docs/api/account/list-workspaces.md) |

### Plants

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:plants` | Read plant records | Any member | Teams, Enterprise | [`GET /plants`](https://docs.xplantpro.com/docs/api/plants/list-plants.md)<br />[`GET /plants/{id}`](https://docs.xplantpro.com/docs/api/plants/get-plant.md) |
| `write:plants` | Create and update plant records | `member` | Teams, Enterprise | [`POST /plants`](https://docs.xplantpro.com/docs/api/plants/create-plant.md)<br />[`PATCH /plants/{id}`](https://docs.xplantpro.com/docs/api/plants/update-plant.md) |

### Explants

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:explants` | Read explant records | Any member | Teams, Enterprise | [`GET /explants`](https://docs.xplantpro.com/docs/api/explants/list-explants.md)<br />[`GET /explants/{id}`](https://docs.xplantpro.com/docs/api/explants/get-explant.md) |
| `write:explants` | Create and update explant records | `member` | Teams, Enterprise | [`POST /explants`](https://docs.xplantpro.com/docs/api/explants/create-explant.md)<br />[`PATCH /explants/{id}`](https://docs.xplantpro.com/docs/api/explants/update-explant.md) |

### Contaminations

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:contaminations` | Read contamination logs | Any member | Teams, Enterprise | [`GET /contaminations`](https://docs.xplantpro.com/docs/api/contaminations/list-contaminations.md)<br />[`GET /contaminations/{id}`](https://docs.xplantpro.com/docs/api/contaminations/get-contamination.md) |
| `write:contaminations` | Submit contamination observations | `member` | Teams, Enterprise | [`POST /contaminations`](https://docs.xplantpro.com/docs/api/contaminations/create-contamination.md) |

### Tasks

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:tasks` | Read scheduled tasks and due work | Any member | Teams, Enterprise | [`GET /tasks`](https://docs.xplantpro.com/docs/api/tasks/list-tasks.md)<br />[`GET /tasks/{id}`](https://docs.xplantpro.com/docs/api/tasks/get-task.md)<br />[`GET /tasks/demand`](https://docs.xplantpro.com/docs/api/tasks/list-demand-signals.md) |
| `write:tasks` | Create, update, complete, and reopen tasks | `member` | Teams, Enterprise | [`POST /tasks`](https://docs.xplantpro.com/docs/api/tasks/create-task.md)<br />[`PATCH /tasks/{id}`](https://docs.xplantpro.com/docs/api/tasks/update-task.md) |
| `write:demand` | Push sales/order demand numbers per genus for task prioritization | `manager` | Teams, Enterprise | [`POST /tasks/demand`](https://docs.xplantpro.com/docs/api/tasks/create-demand-signal.md) |

### Comments

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:comments` | Read notes and comments on lab records | Any member | Teams, Enterprise | [`GET /comments`](https://docs.xplantpro.com/docs/api/comments/list-comments.md) |
| `write:comments` | Add notes and comments to lab records | `member` | Teams, Enterprise | [`POST /comments`](https://docs.xplantpro.com/docs/api/comments/create-comment.md) |

### Media

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:assets` | Read photos and media attached to lab records | Any member | Teams, Enterprise | [`GET /assets`](https://docs.xplantpro.com/docs/api/media/list-assets.md)<br />[`GET /assets/{id}`](https://docs.xplantpro.com/docs/api/media/get-asset.md) |
| `write:assets` | Attach photos and media to lab records | `member` | Teams, Enterprise | [`POST /assets`](https://docs.xplantpro.com/docs/api/media/create-asset.md) |
| `read:media_recipes` | Read media recipe data | Any member | Teams, Enterprise | [`GET /media-recipes`](https://docs.xplantpro.com/docs/api/media/list-media-recipes.md)<br />[`GET /media-recipes/{id}`](https://docs.xplantpro.com/docs/api/media/get-media-recipe.md) |
| `write:media_recipes` | Create and update media recipes | `member` | Teams, Enterprise | [`POST /media-recipes`](https://docs.xplantpro.com/docs/api/media/create-media-recipe.md)<br />[`PATCH /media-recipes/{id}`](https://docs.xplantpro.com/docs/api/media/update-media-recipe.md) |

### Transfers

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:transfers` | Read transfer and stage history for plants and explants | Any member | Teams, Enterprise | [`GET /stages`](https://docs.xplantpro.com/docs/api/transfers-and-stages/list-stages.md)<br />[`GET /transfers`](https://docs.xplantpro.com/docs/api/transfers-and-stages/list-transfers.md) |
| `write:transfers` | Record transfers and advance the stage of plants and explants | `member` | Teams, Enterprise | [`POST /stages`](https://docs.xplantpro.com/docs/api/transfers-and-stages/create-stage.md)<br />[`POST /transfers`](https://docs.xplantpro.com/docs/api/transfers-and-stages/create-transfer.md) |

### SOPs

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:sops` | Read SOP templates and steps | Any member | Teams, Enterprise | [`GET /sops`](https://docs.xplantpro.com/docs/api/sops/list-sops.md)<br />[`GET /sops/{id}`](https://docs.xplantpro.com/docs/api/sops/get-sop.md) |
| `read:sop_runs` | Read SOP execution history: who ran which step, when | Any member | Teams, Enterprise | [`GET /sop-runs/{id}`](https://docs.xplantpro.com/docs/api/sops/get-sop-run.md) |
| `write:sop_runs` | Create and advance SOP run sessions | `member` | Teams, Enterprise | [`POST /sop-runs`](https://docs.xplantpro.com/docs/api/sops/create-sop-run.md) |
| `write:sop_steps` | Post confirmations, scans and measurements against a step of an SOP run | `member` | Teams, Enterprise | [`POST /sop-runs/{id}/steps/{stepId}/events`](https://docs.xplantpro.com/docs/api/sops/create-sop-step-event.md)<br />[`POST /sop-runs/{id}/steps/{stepId}/measurements`](https://docs.xplantpro.com/docs/api/sops/create-sop-step-measurement.md) |

### Labels

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:labels` | Resolve QR/barcode label codes to entity records | Any member | Teams, Enterprise | [`GET /labels/resolve`](https://docs.xplantpro.com/docs/api/labels/resolve-label.md) |
| `write:label_scans` | Submit label scan events | `member` | Teams, Enterprise | [`POST /label-scans`](https://docs.xplantpro.com/docs/api/labels/create-label-scan.md) |

### Devices

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:devices` | List registered devices and their status | Any member | All paid plans | [`GET /devices`](https://docs.xplantpro.com/docs/api/devices/list-devices.md)<br />[`GET /devices/{deviceId}/tokens`](https://docs.xplantpro.com/docs/api/devices/list-device-tokens.md) |
| `write:devices` | Register devices, send heartbeats, and manage device tokens | `member` | All paid plans | [`POST /devices`](https://docs.xplantpro.com/docs/api/devices/create-device.md)<br />[`POST /devices/{deviceId}/heartbeat`](https://docs.xplantpro.com/docs/api/devices/send-heartbeat.md)<br />[`POST /devices/{deviceId}/tokens`](https://docs.xplantpro.com/docs/api/devices/create-device-token.md)<br />[`DELETE /devices/{deviceId}/tokens/{tokenId}`](https://docs.xplantpro.com/docs/api/devices/revoke-device-token.md) |
| `read:sensor_readings` | Query historical sensor readings | Any member | Teams, Enterprise | [`GET /sensor-readings`](https://docs.xplantpro.com/docs/api/sensor-readings/list-sensor-readings.md) |
| `write:sensor_readings` | Submit environmental sensor readings (temperature, humidity, etc.) | `member` | All paid plans | [`POST /sensor-readings`](https://docs.xplantpro.com/docs/api/sensor-readings/create-sensor-readings.md) |
| `write:device_events` | Submit device status events | `member` | All paid plans | [`POST /device-events`](https://docs.xplantpro.com/docs/api/devices/create-device-event.md) |

### Equipment

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:equipment` | Read the lab equipment library and its maintenance history | Any member | Teams, Enterprise | [`GET /equipment`](https://docs.xplantpro.com/docs/api/equipment/list-equipment.md)<br />[`GET /equipment/{id}`](https://docs.xplantpro.com/docs/api/equipment/get-equipment.md)<br />[`GET /equipment/{id}/events`](https://docs.xplantpro.com/docs/api/equipment/list-equipment-events.md) |
| `write:equipment_events` | Record that a piece of equipment was used, calibrated, serviced or faulted | `member` | Teams, Enterprise | [`POST /equipment/{id}/events`](https://docs.xplantpro.com/docs/api/equipment/create-equipment-event.md) |

### Commercial

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:pricing` | Read culture line prices, pricing tiers, and price history | `manager` | Teams, Enterprise | [`GET /pricing/culture-lines`](https://docs.xplantpro.com/docs/api/commerce/list-culture-line-prices.md)<br />[`GET /pricing/events`](https://docs.xplantpro.com/docs/api/commerce/list-price-events.md) |
| `read:commerce` | Read store order lines and sell-through summaries | `manager` | Teams, Enterprise | [`GET /commerce/order-lines`](https://docs.xplantpro.com/docs/api/commerce/list-order-lines.md)<br />[`GET /commerce/sell-through`](https://docs.xplantpro.com/docs/api/commerce/get-sell-through.md) |

### History

| Scope | Allows | Minimum role | Plans | Endpoints |
| --- | --- | --- | --- | --- |
| `read:events` | Read plant and explant edit history (audit events) | Any member | Teams, Enterprise | [`GET /events`](https://docs.xplantpro.com/docs/api/change-history/list-change-events.md) |

### No scope needed

- [`GET /me`](https://docs.xplantpro.com/docs/api/account/get-me.md): Get the calling key