API access

“Just give me an API key and I’ll do the rest” is the first thing asked in any integration, and the honest answer is this: there is no single key to the whole platform. There are three different doors, each with its own scope and its own lifetime. Which door you take is decided not by convenience but by what the external system actually has to do.

1. The application JWT — for the interface itself

Signing in returns a JWT: this is what the browser signs every request to /api/… with. The token lives for a day and is revoked by bumping the user’s token version; the role is read from the database on every request — so promoting or demoting takes effect immediately rather than after the token is re-issued.

Technically you can use it from your own program too: the Authorization: Bearer <token> header, base path /api. But this is a human session token, not a key issued to an integration: it expires in a day, it has no separate permissions, and everything it does is done on your behalf. As a foundation for a permanent integration it is a poor one.

2. The webhook key — for one workflow

The most common task: “from my CRM (a form, a script, a backend) run this workflow and get an answer back”. There is a dedicated channel for it — the webhook. The key is created on the first publish to that channel, is bound to one workflow and grants nothing beyond the right to run it.

The address and the key are shown on the Deploy tab, channel Webhook: the same place has the Show key button and a ready-made Request example, which is easier to copy than to type.

curl -X POST https://your-domain/webhook/<workflow-id> \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"message": "hello", "data": {"order_id": 12345}}'

About the request body: it must be a JSON object, and it must contain at least one of two fields. message is a string, it is stored as the user’s message and arrives at the workflow input; data is an arbitrary value, available in the trigger context as trigger.webhook.payload. Neither one present means a 400.

The response arrives after the run has finished: the handler queues the work and waits for a terminal status for up to five minutes.

{
  "status": "success",
  "result": { "output": "…whatever the workflow exit returned…" },
  "session_id": "…",
  "execution_id": "…"
}

Read that response by three rules, each of which saves a day of debugging:

• status is success only for a successful run. A run where a node failed with an unhandled error but still reached the exit (status partial) answers with "status": "error" while still putting the output into result — you cannot tell success from failure by the presence of result alone. Statuses are covered in Statuses.
• On failure the error field carries a machine code, not the exception text: it is meant for branching inside your system. The human-readable description of the failure lives in Runs, with the workflow author.
• The session_id from the response can be put into the path — POST /webhook/<id>/<session_id> — and the next call continues the same conversation, with the same history and memory. Without it every call starts a new session. The identifier must be an existing session of this workflow, otherwise you get a 404.

The individual responses you will see most often: 401 — no key, or the wrong one; 410 — the workflow is not published or the “Webhook” channel is off; 429 — the rate limit was exceeded (counted per caller IP address) or the plan’s queue-depth limit for this session; "error": "timeout" inside the response — the run did not finish within five minutes but is still going, and its outcome has to be checked in “Runs” by execution_id.

3. The Assistant MCP key — for the whole workspace

The third door is meant not for an arbitrary program but for an external AI agent (Claude Code, for example): it connects over the MCP protocol and works through tools — it reads the workflow list, fetches a graph, edits, validates, runs it, reads logs, goes into knowledge bases, collections, files and chat history. Details on the Assistant MCP page.

The key is issued per workspace, starts with amcp_, is shown once (only its fingerprint is stored on the server) and is managed in Settings → Assistant MCP: Generate key, Rotate key and the Permissions set — a checkbox per capability. Only a workspace administrator can manage the key; by default access is read-only, and the server does not merely hide forbidden tools, it re-checks the permission at call time.

Two things worth knowing up front. Runs made by the agent are billed to the workspace owner like any others — an agent looping over a workflow spends real credits. And the key stops working once the workspace is archived: that is deliberate, otherwise an archive would stay fully operational over MCP.

What is not an API key

A public chat link and a widget token are publication, not API access. The token in the address gives an unauthenticated visitor the right to talk to one published workflow and nothing more: no reading of other people’s data, no management. It is public by design — handing the link around is the whole point. See Chat by link and Website widget.

Workspace secrets are access outwards, not inwards. The keys you put into integrations and secrets are what the workflow needs in order to reach other services; they have nothing to do with the platform itself.

If you really need “programmatic access to everything”

No such token exists today: no service accounts, no OAuth applications, no per-workspace REST keys. The closest thing is Assistant MCP: by coverage it is programmatic access to the platform (workflows, versions, publishing, running, cancelling, executions, logs, knowledge bases, collections, files, chat history) — just in the form of MCP tools rather than REST endpoints. The rules are simple: need to trigger one workflow from another system — webhook; need to drive the platform from a program — Assistant MCP.