API keys and scopes

Each key belongs to one farm and can only do what was selected. Whoever creates a key can only grant scopes they hold themselves. Create and revoke keys in Manage › API keys.

Sending the key

Use either header (the gateway accepts both):

Example

Authorization: Bearer nfk_...
X-Api-Key: nfk_...

Node.js

const res = await fetch("https://api-prod.nextfarm.vn/api/v1/iot/devices?status=offline", {
  headers: { Authorization: `Bearer ${process.env.NEXTFARM_API_KEY}` },
});
const { items } = await res.json();

Scopes

Maps & seasons

Scope	Allows
`gis.parcels.view`	View parcels and seasons
`gis.zones.view`	View zones
`gis.farmers.view`	View farmers
`gis.crop-types.view`	View crop types
`gis.facilities.view`	View facilities
`gis.layers.view`	View map layers

IoT (read-only)

Scope	Allows
`iot.devices.view`	View devices
`iot.telemetry.view`	View sensor readings
`iot.telemetry.export`	Export sensor readings
`iot.alerts.view`	View alerts

Harvest & traceability

Scope	Allows
`farm-harvest.harvest.view`	View harvest batches
`farm-harvest.harvest.create`	Create harvest batches (write)
`farm-harvest.qr-codes.view`	View QR labels
`farm-harvest.trace.view`	View traceability
`farm-harvest.certification.view`	View certificates
`farm-harvest.market-prices.view`	View market prices

Farm books & tasks

Scope	Allows
`office.base.record.view`	View book data
`office.base.record.manage`	Add and edit book rows (write)
`office.task.view`	View tasks
`office.calendar.view`	View calendar

Reports

Scope	Allows
`report.view`	View reports
`report.export`	Export reports

Safety limits

API keys, webhooks and MCP never control devices — there is no scope for switching or configuring devices, and the gateway blocks every IoT write route for keys.

Keys are read-only, except: creating/editing harvest batches and adding/editing farm book rows. Nothing can be deleted.
No access to user administration, permission groups, or creating other keys.
Revocation takes effect immediately; keys can expire (30 days, 90 days, 1 year) or never expire.

Error codes

Code	Meaning
`401`	The key is wrong, expired or revoked.
`403`	The key lacks a scope, or the route does not accept API keys (see the detail field).
`404`	Data not found.
`422`	The request data is invalid (the errors field lists each problem).
`429`	Too many requests — read Retry-After, then try again.

Timestamps are returned in UTC (ISO 8601). Lists paginate with page, page_size. JSON request and response bodies use snake_case (e.g. parcel_id) — camelCase keys in a body are ignored.

Full security rules for partners: Security →