Scopes

Scopes restrict which endpoints member-level API keys (sk-epoch-) and organisation-level API keys (ok-epoch-) can call.

Scope reference

Scope	Endpoints
`locations:read`	`GET /locations/facilities` `GET /locations/facilities/:id` `GET /locations/facilities/:id/sheds` `GET /locations/plots` `GET /locations/plots/:id` `GET /locations/sheds` `GET /locations/sheds/:id`
`locations:delete`	`DELETE /locations/facilities/:id` `DELETE /locations/sheds/:id` `DELETE /locations/plots/:id`
`metrics:read`	`GET /metrics/plots/:metric` `GET /metrics/plots/:location_id/:metric` `GET /metrics/sheds/:metric` `GET /metrics/sheds/:location_id/:metric`
`ingestions:read`	`GET /ingestions` `GET /ingestions/:id` `GET /ingestions/:id/summary` `GET /ingestions/assets` `GET /ingestions/assets/:id`
`ingestions:write`	`POST /discovery/source/:taskId/ingest` `POST /ingestions/assets` `PUT /ingestions/assets`
`parcels:read`	`GET /cadastral/tasks` `GET /cadastral/tasks/:id` `GET /cadastral/tasks/:id/summary` `GET /cadastral/parcels/results` `GET /cadastral/parcels/results/:id`
`parcels:write`	`POST /cadastral/parcels/search` `POST /cadastral/parcels/results/:id/ingest`
`tags:read`	`GET /tags`
`tags:write`	`PATCH /tags/:name` `DELETE /tags/:name`
`webhooks:read`	`GET /webhooks` `GET /webhooks/:id` `GET /webhooks/:id/deliveries` `GET /webhooks/:id/deliveries/:deliveryId`
`webhooks:write`	`POST /webhooks` `PATCH /webhooks/:id` `DELETE /webhooks/:id` `POST /webhooks/:id/verify` `POST /webhooks/:id/rotate-secret`
`notifications:read`	`GET /notifications` `GET /notifications/:id`
`notifications:write`	`PATCH /notifications/:id` `POST /notifications/mark-read` `DELETE /notifications/:id`
`artifacts:read`	`GET /artifacts` `GET /artifacts/:id` `GET /artifacts/:id/signed-urls`
`artifacts:write`	`POST /artifacts` `DELETE /artifacts/:id`
`artifacts:sign`	`POST /artifacts/:id/signed-urls`
`auth:read`	`GET /auth/me`
`imagery:read`	`POST /imagery/tiles`
`assessments:read`	`GET /assessments/tasks` `GET /assessments/tasks/:id`
`assessments:write`	`POST /assessments/:locationType/:id/:slug/refresh` `POST /assessments/:locationType/:idOrSlug/refresh` `POST /assessments/:locationType/refresh`
`parties:read`	`GET /parties/suppliers` `GET /parties/suppliers/:id`
`parties:write`	`POST /parties/suppliers` `DELETE /parties/suppliers/:id` `PATCH /parties/suppliers/:id` `POST /parties/suppliers/:id/locations`
`geocode:read`	`GET /discovery/source/:taskId/decisions` `GET /discovery/source/:taskId/results` `GET /discovery/source/:taskId/status` `POST /discovery/validate` `GET /discovery/validate/:taskId/results` `GET /discovery/validate/:taskId/status`
`discovery:write`	`POST /discovery/source` `POST /discovery/source/:taskId/decisions`
`organizations:read`	`GET /organizations/children` `GET /organizations/children/:id` `GET /organizations/children/:id/keys` `GET /organizations/me`
`organizations:write`	`POST /organizations/children` `DELETE /organizations/children/:id` `PATCH /organizations/children/:id` `POST /organizations/children/:id/keys` `DELETE /organizations/children/:id/keys/:keyId` `PATCH /organizations/me`
`billing:read`	`GET /ingestions/:id?include=payment` — enables the block; a key without it still gets the task `GET /ingestions/:id/checkout-session` `POST /ingestions/:id/cost-estimate` `GET /organizations/:id/checkout-sessions/:sessionId` `GET /organizations/:id/credits` `GET /organizations/:id/credits/subscriptions` `GET /organizations/:id/subscription` Also required to read `credit_refusal.required` and `credit_refusal.available` on `GET /ingestions/:id/summary`. Without it, the rest of the marker is still served.
`billing:write`	`POST /ingestions/:id/checkout-session` `DELETE /organizations/:id/subscription` `POST /organizations/:id/subscription/resume`
`rate_limits:read`	`GET /rate-limits`
`artifacts:download`	Reserved. Accepted on a key and stored, but no endpoint requires it today. Artifact downloads are authorised by `artifacts:read` plus `artifacts:sign`.
`eudr:read`	Every `GET` under `/regulations/eudr` — the audit-trail record, its versions, plots, suppliers, events, attachments, reports and tasks, plus `GET /regulations/eudr/scope`, `/scope/entries` and `/species`. Includes the TRACES read-through: `GET /regulations/eudr/audit-trail/:recordId/traces` `GET /regulations/eudr/audit-trail/:recordId/traces/statement` `GET /regulations/eudr/audit-trail/:recordId/versions/:versionId/traces` `GET /regulations/eudr/audit-trail/:recordId/versions/:versionId/traces/statement`
`eudr:write`	Every `POST`, `PATCH`, `PUT` and `DELETE` under `/regulations/eudr` — creating and editing records, config, data fields, verdict overrides, attachments, suppliers and authorisations, and `POST /regulations/eudr/dds/:recordId/submit`
`eudr:verify`	`POST /regulations/eudr/dds/lookup` Also required to read the live half of a `manual` filing's TRACES data on the four read-through routes above. See the note below.
`eudr:reference`	Only `GET /regulations/eudr/scope`, `GET /regulations/eudr/scope/entries` and `GET /regulations/eudr/species` — HS-code classification, Annex I entries and species reference data.

Grant only eudr:reference to restrict a key to these three reference endpoints. They also continue to accept eudr:read. The reference scope does not grant access to audit trails, DDS records, organisation data or EUDR mutations.

Bulk classification through POST /regulations/eudr/scope/review still requires eudr:read; it is not included in eudr:reference.

Reference-only EUDR key

For an integration that only classifies HS codes or lists Annex I entries and species, select EUDR reference data (eudr:reference) when creating or editing the key in Settings → API Keys. Select no other scopes.

When creating a child organisation key through POST /organizations/children/:id/keys, use this request body:

{
  "data": {
    "type": "api_key",
    "attributes": {
      "name": "EUDR reference lookups",
      "scopes": ["eudr:reference"]
    }
  }
}

Authenticate the creation request with a parent organisation key that has organizations:write. Use the newly returned key for the three reference endpoints. Other scope-protected endpoints, including GET /auth/me and the EUDR audit-trail routes, return 403 Insufficient scope with that key.

Existing eudr:read keys continue to work; no key update is required. An empty scope list grants unrestricted access, so keep ["eudr:reference"] set on a reference-only key.

Why `eudr:verify` is separate from `eudr:read`

eudr:read covers data fm-api can tie to your organisation. eudr:verify covers data it cannot.

POST /regulations/eudr/dds/lookup resolves reference and verification numbers that may belong to anyone, so it is a TRACES proxy by construction — a read-scoped key must not reach it by default. The same reasoning applies to a DDS recorded with mode: "manual": those identifiers came from you, not from TRACES, so nothing in our data proves your organisation owns them. The read-through routes serve their stored values to any eudr:read key but withhold the live TRACES half without eudr:verify.

Grant eudr:verify to keys that check counterparties' statements. Leave it off keys that only read your own filings.

Scope rules

API keys with no scopes (null or empty) have access to all endpoints. This is the default.
API keys with scopes set can only access endpoints matching their scopes. All other endpoints return 403 Insufficient scope.

Common configurations

Use case	Scopes	Resource tags
Read-only access	`locations:read`, `metrics:read`, `ingestions:read`, `auth:read`	(none)
Full access	(none — leave empty)	(none)
Supplier key	`locations:read`, `auth:read`	`region:brazil`, `supplier:acme`
Ingestion bot	`ingestions:read`, `ingestions:write`	(none)
EUDR reference lookups only	`eudr:reference`	(none)