One key,
one organisation.

Scope, errors and limits

Organisation

Every tenant endpoint names the organisation in its path. A key presented against an organisation that is not its own is answered 404, the same answer a person who is not a member gets: the response never distinguishes “not yours” from “does not exist”.

Errors

One envelope, everywhere. code is stable and safe to branch on; message is for people and may be reworded between releases. Quote request_id when you report a fault — it identifies the request in our logs.

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "request_id": "9f2c1d0a4b6e8f1c",
    "fields": { "expires_on": "An expiry cannot precede the start date." }
  }
}

Rate limits

Counted per caller — per key for a key, per person for a person — so one runaway script cannot spend a colleague’s allowance. Over it, you get 429 and a Retry-After header. Wait for it rather than retrying immediately.

Pagination

Lists are keyset paginated: follow next_cursor, never an offset, so a page cannot shift under you while a colleague is editing.

Dates

An expiry is a calendar date, not an instant. A permit expiring on 31 March expires on the 31st where the site is, and a site in another country keeps its own calendar.

Versioning

This is version 1.0.0, served under /v1. Within a major version we add fields and endpoints; we do not remove or rename them, and we do not change what an existing code means. Decode responses in a way that tolerates a field you have not seen before.

The machine-readable specification is served by every deployment at /openapi.json, without a credential. It is generated from the service’s routing table and checked in CI, so it describes the service that is actually running.

Endpoints

Generated from the routing table. Request and response bodies are deliberately not listed here: those live in the handlers, and a copy of them on this page would be the one part of it that could quietly go stale.