Organizations
Read and manage the acting organisation and its parent-child relationships. A parent organisation can create, list, update, remove, and delete child organisations. Only single-level hierarchy is supported — a child organisation cannot itself have children.
▶Use cases
- Self-service defaults — read (
GET /organizations/me) and set (PATCH /organizations/me) the acting organisation's EUDR operator defaults, including while acting-as a child - Billing display — read the credit balance
(
GET /organizations/:id/credits) to show what an organisation can spend - Plan selection — read the priced tier catalogue
(
GET /organizations/:id/credits/subscriptions) and the organisation's current plan (GET /organizations/:id/subscription) - Multi-tenant management — create sub-organisations for different business units, subsidiaries, or partners
- Delegated access — use
x-acting-ason other endpoints to query data scoped to a child organisation - Lifecycle management — remove a child (promoting it to top-level) or permanently delete it with all associated data
▶Endpoints
▶The acting organisation
| Method | Path | Description |
|---|---|---|
| GET | /organizations/me | Read the acting organisation + its operator defaults |
| PATCH | /organizations/me | Set operator defaults on the acting organisation |
▶Credits and subscriptions
| Method | Path | Description |
|---|---|---|
| GET | /organizations/:id/credits | Read an organisation's credit balance |
| GET | /organizations/:id/credits/subscriptions | Read the priced self-serve tier catalogue |
| GET | /organizations/:id/subscription | Read the organisation's current plan, or null |
Unlike the children endpoints, these take any organisation in the
caller's scope — your own or a child — and work while acting-as.
The current-plan route is singular: an organisation can hold only one
subscription. It returns 200 with null when there is none, and never
404 for "no subscription".
▶Child organisations (see the Children folder)
| Method | Path | Description |
|---|---|---|
| GET | /organizations/children | List all child organisations |
| POST | /organizations/children | Create a new child organisation |
| GET | /organizations/children/:id | Get a child organisation by ID |
| PATCH | /organizations/children/:id | Update a child organisation's name + operator defaults |
| DELETE | /organizations/children/:id | Delete a child organisation (requires confirmation) |
| GET | /organizations/children/:id/keys | List API keys for a child organisation |
| POST | /organizations/children/:id/keys | Create an API key for a child organisation |
| DELETE | /organizations/children/:id/keys/:keyId | Delete an API key for a child organisation |
▶Access control
/organizations/meoperates on the acting organisation and is the only org endpoint allowed while acting-as (x-acting-as). It never changes the organisation name — operator defaults only.- The
/organizations/children/*endpoints require the caller to be a top-level organisation (not a child) and are blocked when acting-as. - Permanent deletion requires the
x-confirm-delete: trueheader. - API key management enforces a limit of 20 manually-created keys per child organisation.
Required scope:
organizations:readfor reads (me, list, get),organizations:writefor writes (me, create, update, remove, delete),billing:readfor the credit balance