Authentication and API keys

Authenticate API requests with the x-api-key header, choose the scopes a key needs, and create or revoke keys under Settings and API keys.

Every request to the Loopfour API carries an API key in the x-api-key header. A key belongs to one company and holds a list of scopes. Each endpoint checks for the scope it needs.

Base URL

https://workflow.loopfour.ai/api/v1

Send the key

curl https://workflow.loopfour.ai/api/v1/workflows \
  -H "x-api-key: $LOOPFOUR_API_KEY"

Keys start with wfk_live_ or wfk_test_, followed by 32 random characters. A header in any other shape is refused with 401 and the message Invalid API key format.

Keep keys on your server. Do not put a key in browser code, a public repository or a log line. Anyone holding the key can do what its scopes allow.

Create a key in Studio

Open Settings and select API keys.

Select Create key. Enter a Key name, such as "ERP sync", and choose an Expiration: 1 week, 1 month, 3 months, 6 months, 1 year, 3 years or Never. The default is 1 year.

Select Create Key. Copy the key from the dialog. Studio shows it once; Loopfour stores only a hash and the first few characters.

A key created in Studio gets this fixed set of scopes: workflows:read, workflows:write, workflows:execute, connections:read, connections:write, runs:read, runs:write and webhooks:manage. To get a key with a different set, create it through the API (below).

The API keys list shows each key's Name, Key (the stored prefix), Created, Expires and Last Used values. Revoke deletes the key at once; requests that use it then fail with 401.

Scopes

Scope	Lets the key
`workflows:read`	List and read workflows, versions and schedules; validate a workflow file. Also accepted on run, table, file, dashboard and audit-log reads (see below)
`workflows:write`	Create, update, activate, pause, archive and roll back workflows; create API keys. Also accepted on table, file, dashboard and approval writes
`workflows:execute`	Start a run, start a scheduled run now, and cancel, retry or restart a run
`runs:read`	Read runs and run logs
`runs:write`	Defined, but no endpoint checks it today
`connections:read`	List and read connections
`connections:write`	Create, update and remove connections
`connections:connect`	Start a new connection through a Studio connect link, nothing more
`secrets:read`	List a workflow's secrets (values are masked)
`secrets:write`	Create, rotate and delete workflow secrets
`webhooks:manage`	Manage the endpoints Loopfour sends run events to
`tables:read`, `tables:write`	Read or change data tables
`files:read`, `files:write`	Read or change workspace files
`dashboards:read`, `dashboards:write`	Read or change dashboards and widgets
`approvals:decide`	Approve or reject a pending approval
`audit:read`	Read the audit log

Some newer scopes sit next to an older one that the same route still accepts, so existing keys keep working. For an API key, workflows:read passes wherever runs:read, tables:read, files:read, dashboards:read or audit:read is checked. workflows:write passes wherever tables:write, files:write, dashboards:write or approvals:decide is checked, and connections:write passes for connections:connect.

workflows:write is enough to create a new API key with any scopes. Give it only to systems you would trust with full access to the company.

Manage keys through the API

Create a key (workflows:write):

curl -X POST https://workflow.loopfour.ai/api/v1/auth/api-keys \
  -H "x-api-key: $LOOPFOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Month-end reporting",
    "scopes": ["workflows:read", "runs:read", "tables:read"],
    "expiresAt": "2027-12-31T00:00:00.000Z"
  }'

Field	Type	Required	Meaning
`name`	string, 1 to 255 characters	Yes	A label you will recognise later
`scopes`	array of scope strings	Yes, at least one	Scopes from the table above
`expiresAt`	ISO 8601 date-time	No	Leave it out for a key that does not expire

The 201 response holds the full key in data.key. It is returned only here.

{
  "success": true,
  "data": {
    "id": "6f1c2d3e-0000-4000-8000-000000000001",
    "name": "Month-end reporting",
    "key": "wfk_live_q3V9...",
    "keyPrefix": "wfk_live_q3V9",
    "scopes": ["workflows:read", "runs:read", "tables:read"],
    "expiresAt": "2027-12-31T00:00:00.000Z",
    "createdAt": "2026-11-12T10:00:00.000Z"
  }
}

A new key has the same environment (live or test) as the key that created it.

List keys: GET /auth/api-keys returns id, name, keyPrefix, scopes, expiresAt, lastUsedAt and createdAt for each key in the company. The secret is never returned.

Revoke a key: DELETE /auth/api-keys/:id deletes the key and returns { "success": true, "data": { "deleted": true } }, or 404 with code NOT_FOUND when no key with that id exists in the company.

Rotate a key

Create a new key with the same scopes.
Deploy it to the systems that call Loopfour.
Check that requests succeed with the new key. Its Last Used value updates.
Revoke the old key. Both keys work until you do.

Authentication errors

Status	Code	When
`401`	`UNAUTHORIZED`	No key or session, the key has the wrong format, the key is unknown or revoked, or the key has expired (`API key has expired`)
`403`	`FORBIDDEN`	The key is valid but lacks the scope. The message names it, for example `Missing required scopes: workflows:execute`

Both use the standard error body described in Errors, retries and timeouts.

Rate limits

Requests are counted per API key over a one-minute window.

Category	Limit per minute	Used by
Read	1,000	Most `GET` requests
Write	100	Most `POST`, `PUT`, `PATCH` and `DELETE` requests
Execute	500	Starting, cancelling, retrying and restarting runs

Inbound webhook routes are limited per sending IP address instead (10,000 per minute).

Rate-limited responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time in seconds). Over the limit, the API returns 429 with code RATE_LIMITED and a Retry-After header in seconds. Wait that long before you retry.