API Keys

Required Access Level

Admin or Super Admin

What are API Keys for?

API Keys let external systems reach the Flowi Agentic API programmatically, with no user login. They are used for:

• Integrations with ERPs, tax systems, portals
• External automations that need to start processes or query data
• Scripts and command-line tools

Creating an API Key

1. Go to Integration → API Keys
2. Click New API Key
3. Give it a descriptive name (e.g. "SAP ERP integration")
4. Set the requests-per-minute limit — 100 by default, 0 for unlimited
5. Tick the scopes the integration needs — at least one is required
6. Click Generate

The generated key is shown only once. Copy it and store it somewhere safe before closing the dialog.

The limit and the scopes can also be changed later, on the same screen, under Edit key. The change takes effect on the next request, with nothing to restart.

The limit counts requests per minute for that key. Past it, the API answers 429 Too Many Requests until the minute rolls over. A 0 turns the counting off: use it carefully, because it is the only protection against an integration stuck in a loop.

The number here belongs to the whole installation, with one pod or with five: the count lives in a shared table, not in each replica's memory. That was not true until 2026-08-28 — two replicas handed out twice the budget while this screen kept showing the original number. The window is fixed, not sliding: at the turn of the minute an integration can spend its whole allowance twice in a row.

The scopes: what each one opens

There are two scopes, and they are the only ones the screen offers:

Scope	What it opens	HTTP methods
read	Every read of the tenant API: list instances, fetch a task, read a CMS collection, download a report	GET, HEAD, OPTIONS
write	Every write: start a process, complete a task, write to the CMS, revoke something, delete a record	POST, PUT, PATCH, DELETE

The two do not imply one another. A key ticked only with write is refused on a GET, exactly as a read-only key is refused on a POST. An integration that both reads and writes carries both.

A request without the scope it needs gets 403 Forbidden, with the missing scope named:

{
  "error": "Forbidden",
  "message": "Esta chave de API tem os escopos [read] e o método POST exige o escopo 'write'. Marque esse escopo na chave em Integração → API Keys, ou use uma chave que já o tenha."
}

The cut is by HTTP method, not by route. That has exactly one practical consequence: an endpoint that only queries but is exposed as a POST — a search with filters in the body, say — requires write. If a read-only integration needs write because of that, it is expected.

Keys that already existed were given both scopes

Until 2026-09-03 the scope field was free text and no route consulted it: a key created as read had exactly the reach of one created as write, and a misspelled scope — forms:submit, which never existed — restricted nothing.

When the release that enforces scopes went up, every key already on record was given read and write, including the blank ones and the ones carrying invented scopes. No integration stopped working because of the change, and none became more restricted than it was.

That means the read-only key you believe you have today probably is not one. Open Integration → API Keys, click Edit key on each row, and untick write on the integrations that only read. That is the only way the restriction starts to apply.

The technical detail, with the authority format and the 429 response body, is in REST API → Authentication.

Security

• Never share an API Key in code repositories or unsafe environments
• Every integration should use its own separate key
• Rotate keys periodically

Using the API Key

Send the key in the header of every request:

X-API-Key: your-key-here

The key identifies the tenant automatically — do not send X-Tenant-ID: on an /api/a/* route the header is refused with 400 before the key is resolved. The tenant comes from the key itself.

Revoking an API Key

Click Revoke on the key's row. Revocation is immediate — any system using that key loses access instantly.

Good practice

Keep a rotation policy. When rotating, create the new key, update the external system, and only then revoke the old one.