API Keys

Looking for the product view?

The Help Center explains this surface as users see it: API Routes & Webhooks.

An API key lets an outside system (a script, a scheduler, another platform, a CI job) call an App's own server routes without a browser session. A key runs as the person who created it and reaches only that one App.

What a key can reach

A key is scoped to the App it was minted for, and within that App to its own routes only:

Request	Result
GET <base>/agenda	The App's server/agenda.js handler
GET <base>/_server/agenda	The same handler, explicit spelling
GET <base>/datasets/123/_search	403 when the manifest declares that path in access.apis
The App's host page, assets, MCP endpoint or webhooks	403
Any other Informer API	403

The base URL is the servers[0].url value in the App's openapi.json, which also advertises the bearer scheme. The App itself reads the same value as request.app.apiUrl in a server route and window.__INFORMER__.report.apiUrl on the page, so it can show a caller where to send requests. On a deployment that serves Apps from their own origins that is https://<label>.<apps-domain>/api; otherwise it is the App's path-mounted API base on the Informer origin.

A path the App's manifest claims through access.apis belongs to the platform, so a key is refused there. The _server spelling never consults that list, so an App route sitting behind a claimed path stays reachable at <base>/_server/<route>.

Presenting a key

Keys are accepted only in the Authorization header:

curl <base>/work-orders \
  -H "Authorization: Bearer <key>"

?token= and cookie delivery are refused with a 403. That restriction is what lets a key skip the app-origin CSRF check: a bearer credential is never attached by a browser on an attacker's behalf, so it cannot be the subject of a cross-site request.

Two consequences worth knowing:

• Redirects drop the header. Most clients, curl included, strip Authorization when following a redirect. Call the https base URL directly rather than relying on an http redirect.
• token is a reserved query parameter. Informer extracts a credential from ?token= before it reads the header, so an App route cannot receive its own token query parameter.

Informer API keys

A personal Informer API key (token type api, see API Tokens) also calls an App's routes, at the same base URL and in the same Authorization: Bearer <key> header. The request runs as the key's owner, with the App roles that person holds on their shares.

The difference is reach. An App API key is scoped to one App's own routes; an Informer API key is the person's whole credential. Through an App it therefore also reaches the platform APIs the App declares in access.apis, which it could call directly anyway. Prefer an App API key for a system that only needs one App, and an Informer API key when the same script also deploys Apps or calls other Informer APIs, such as a developer's own tooling.

Header delivery is what exempts a request from the app-origin CSRF check, for either kind of key. An Informer API key sent as ?token= still authenticates, but on an App origin a state-changing request carrying it that way is refused with 403 Cross-origin request rejected.

What a key carries

Field	Meaning
notes	The key's name, shown in the keys list and in request logs
data.roles	App roles the key carries, capped at the roles its owner holds
readOnly	When true, only GET requests are accepted
data.publicOnly	When true, only routes marked config.api = 'public' are reachable
expiresAt	Expiry, up to five years out, or null for none
restrict / cidr	Optional network restriction

Roles are a cap, not a grant. The roles chosen at mint are intersected with the owner's live roles on every request, so downgrading someone's share narrows their existing keys immediately, and removing their access stops the keys entirely.

Routes

Method	Path	Gate
GET	/api/apps/{id}/api-keys	The App must be visible to the caller
POST	/api/apps/{id}/api-keys	app:mintKey
GET	/api/apps/{id}/api-keys/_all	app:manage
PUT	/api/apps/{id}/api-keys/_policy	app:manage
PUT	/api/apps/{id}/api-keys/{keyId}	appKey:write
DELETE	/api/apps/{id}/api-keys/{keyId}	appKey:write

app:mintKey is granted to App managers, and to anyone the App is visible to unless a manager turns member self-service off through _policy. appKey:write is granted to a key's own creator and to any App manager.

The personal list also returns heldRoles, the roles the caller holds on the App, so a client can offer exactly the roles a mint would accept.

Creating a key

POST /api/apps/team:field-service/api-keys
Content-Type: application/json

{
  "notes": "Nightly ERP import",
  "roles": ["ingest"],
  "readOnly": false,
  "publicOnly": false,
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

The response is the only place the signed key appears. Every later read of the row omits it, so a lost key is replaced by minting a new one and revoking the old.

Revoking

DELETE removes the row, which is the credential's only anchor, so the key stops authenticating on the next request. There is no grace period and no undo. Rotation is mint-then-revoke: create the replacement, move the caller onto it, then delete the old row.

Keys are excluded from system bundles. A bundle is a shareable artifact and a key is a personal credential, so exporting one would let anyone holding the file call the App as its owner.