Start here

Scopes

A scope is permission to do one kind of thing. Keys are built by ticking the scopes an integration genuinely needs, which keeps the damage small when something goes wrong.

How scopes are named

Scopes read as resource:action. Actions are consistent across resources: read for listing and fetching, write for creating and updating, and a named action where the operation deserves its own switch (projects:send is the obvious one, because it spends a token).

Scopes do not nest. Granting projects:write does not grant projects:read. Most integrations need both.

The full list

Scope	Grants
`projects:read`	List and fetch projects, engagements, documents and activity logs.
`projects:write`	Create and update projects, assign them, add and edit notes, close, complete and reopen.
`projects:send`	Send a project to iwi and request a report. Consumes tokens.
`iwi:read`	Look up iwi, search by name, and resolve coordinates to rohe.
`team:read`	Read team members, pending invitations, receipts, reports and invoices.
`team:write`	Rename the team, change member roles, revoke member access.
`users:invite`	Invite users, resend and expire invitations, including bulk invites.
`groups:read`	List assignment groups.
`groups:write`	Create, update and delete assignment groups.
`files:write`	Request an upload URL and finalise an upload.
`files:read`	Generate download links for documents you already have access to.
`billing:read`	Read token balance, invoices and receipts.

There is no billing:write. Tokens are purchased through Stripe Checkout in the portal, by a human who can see what they are agreeing to. The API can tell you the balance is low. It cannot top it up.

Scopes by job

Four patterns cover most of what people build.

Read only reporting

A dashboard or warehouse sync that never writes anything. Safe to run anywhere, including on a schedule nobody is watching.

projects:readteam:readbilling:read

Consent system integration

Your consenting system creates a project when an application is lodged, attaches the documents and sends it. This is the key that spends money, so keep it on one service and rotate it deliberately.

iwi:readprojects:readprojects:writeprojects:sendfiles:write

Staff provisioning

Driving IwiConnect membership from your HR system or identity provider. Pair it with bulk invites so onboarding a new intake is one call.

team:readteam:writeusers:invitegroups:readgroups:write

When a scope is missing

The API returns 403 with a message naming the scope it wanted. Scopes are checked before anything else runs, so a 403 means nothing was created, updated or charged.

Response · 403

{
  "success": false,
  "message": "This API key is missing the projects:send scope",
  "status_code": 403,
  "response_object": null
}

You cannot add a scope to a key that already exists. Create a new key with the scopes you need, deploy it, then revoke the old one. That is a small annoyance by design: it means a key's powers cannot quietly grow over its life.

Choosing well

Give a key the smallest set that lets it finish its job, and split keys by system rather than by person. A nightly sync and a staff provisioning script should not share a key, because when one of them misbehaves you want to be able to turn it off without breaking the other.