Authentication

Every request to the v3 API — and to the MCP server — is authenticated with an API key sent in the X-API-KEY header. The key identifies your workspace, so there is never a workspace id in a path or a request body, and it also decides who the request acts as.

GET https://api.checkflow.io/v3/auth/test
X-API-KEY: your-api-key-here

Creating an API Key

You must be an Administrator to create, edit or revoke API keys.

Open the Team page and select the API & Integrations tab.
Click Create API Key.
Enter a Name that says what the key is for, such as Zapier or Reporting bot. It can be up to 100 characters.
Choose who the key Acts as — the workspace, or one active Administrator or Member. See Who a Key Acts As.
Optionally, set an Expires date. The key stops working at the end of that day, UTC. Leave it empty for a key that never expires.
Click Create API Key, then copy the key from the dialog.

The key list shows each key's name, who it acts as, when it expires and when it was last used. You can copy a key again from the list at any time. To change a key's name, acting member or expiry, choose Edit from its menu. To stop a key working, choose Revoke.

A workspace can have as many keys as it needs. Give each integration its own key, so that you can revoke one without breaking the others.

warning

A key carries the whole authority of the member it acts as. A key that acts as an Administrator can do anything that Administrator can do, including deleting checklists and templates, and a key that acts as the workspace can do nearly as much — see Keys That Act as the Workspace. Store keys as secrets, never put them in client-side code or a public repository, and revoke a key as soon as you suspect it has been exposed.

Who a Key Acts As

Every request made with a key is made as the member the key acts as, or as the workspace. A key can act as:

Acts as	Meaning
An Administrator	Requests carry that Administrator's identity and access.
A Member	Requests carry that Member's identity, and the checks listed below apply their permissions.
The workspace	Requests act as nobody in particular, through the workspace's anonymous member. The key reads every checklist and passes most permission checks as an Administrator would (see Keys That Act as the Workspace), but cannot use the routes whose subject is a person.

A key can never act as a Guest, and there is no header or parameter that lets a request act as anyone other than the key's member.

What Acting as a Member Changes

Changes are recorded in their name. Activity feeds, comments and notifications show the acting member, as they would if the member had made the change in the app.
The checklist list and search are filtered. GET /v3/checklists and POST /v3/checklists/search return the checklists the member would see in the app's checklist grid, according to their template permissions. A key that acts as the workspace sees every checklist.
"Me" means them. The Tasks grid, saved views and snoozes are the acting member's own.
Running work is checked. Completing a checklist task, marking it not applicable, renaming or completing a checklist, and assigning tasks or setting due dates are refused with 403 FORBIDDEN when the member could not do them in the app.
Reading is checked. A single checklist, its tasks and a standalone task attached to it can be read only when the member could open the checklist in the app: their checklist permission on its template lets them view it, or something in it is assigned to them. A template read by its key is refused when the member's permission on its Library folder is Deny. Data Sets need a Library or Template permission and, for a Data Set filed in a Library folder, View or Edit on that folder; schedules need Schedule.Viewer or Schedule.Creator. The template list is not filtered.

Creating and changing are checked. The app's user permissions apply as they do in the app, together with the template folder permissions and Data Set folder permissions:

To	A Member needs
Create a checklist	Checklist.Creator, and permission to run checklists from the template.
Create a template	Template.Creator.
Publish a version, set a template's permissions, copy a template, commit a draft to a template	Template.Creator, and a permission other than View or Deny on the template's Library folder.
List or upgrade a template's checklists	A permission other than View or Deny on the template's Library folder.
Create a Data Set	Library.Creator.
Change a Data Set, its fields, records or views	Library.Creator, and Edit on the Data Set's Library folder when it is filed in one.
Create, change or delete a schedule, skip a run or create its checklist now	Schedule.Creator — and, to create a schedule or act on a run, permission to run checklists from its template.
Raise, change or delete a standalone task	Task.Creator.
Attach a standalone task to a checklist, or take it off one	Task.Attacher — and, to attach, permission to run checklists from the checklist's template.

Some actions are for Administrators only. Deleting a Data Set, archiving or unarchiving a template, archiving or unarchiving a checklist, and every webhook route — reads included — refuse a key that acts as a Member, whatever permissions the Member has.

A key that acts as an Administrator passes all of these checks. A refusal is 403 FORBIDDEN, and its message says what is missing — a permission, or a folder or template permission — and what an Administrator can do about it. The refusal comes after the resource is looked up, so another workspace's checklist, template, Data Set or schedule is still a 404, never a 403. The webhook routes are the exception: they refuse a Member key before looking anything up. Each resource page sets out the checks its endpoints apply.

Some rules are settings rather than permissions and apply to every key, Administrators included — for example, a standalone task cannot be attached to a checklist whose template has Tasks Can Be Attached switched off, and a checklist cannot be started from an archived template.

Keys That Act as the Workspace

A key that acts as the workspace is the workspace acting for itself. It reads every checklist and its tasks, creates checklists from any template, and passes every permission check on templates, drafts, Data Sets, schedules and webhooks, including the ones limited to Administrators — it can delete Data Sets, archive templates and manage webhooks. It also needs no Task.Creator or Task.Attacher to raise, change or attach standalone tasks. A checklist it creates is created as the workspace's creator.

Its other writes to checklists, checklist tasks and standalone tasks are the exception. For those it acts as the workspace's anonymous member, who is not an Administrator: archiving a checklist is refused; so are the checklist writes that need run permission, unless a template permission grants the anonymous member run access; and it can change or delete only the standalone tasks it raised itself. See Checklists, Checklist Tasks and Standalone Tasks.

Routes That Need a Person

Some routes are about "me": the Tasks grid and its saved views, and snoozing a task (a snooze hides a task from one person's Tasks grid). A key that acts as the workspace has no one to be, so these routes refuse it with 403 and the code API_KEY_ACTS_AS_WORKSPACE. Use a key that acts as a member for them.

When the Member Changes

If the member a key acts as is later deactivated, removed from the workspace or made a Guest, the key stops working and every request answers 401 with the code API_KEY_ACTOR_UNAVAILABLE. An Administrator can fix this by editing the key to act as someone else, or by creating a new key.

Test Your API Key

Checks that a key works and tells you which workspace it belongs to and who it acts as. Call it first when you set up an integration: a key that works against the wrong workspace, or acts as the wrong person, is obvious from this response before you write anything.

GET /v3/auth/test

Parameters

This endpoint takes no parameters.

Example

GET https://api.checkflow.io/v3/auth/test
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "status": "ok",
  "teamId": "6c1d2f0a-93b4-4e7d-a8f2-51c0de7b9a33",
  "teamName": "Acme Corp",
  "region": "US",
  "isEnterprise": true,
  "apiKey": {
    "name": "Reporting bot",
    "createdDateTime": "2026-09-01T10:15:00Z",
    "actsAs": {
      "type": "member",
      "id": 1042,
      "email": "sarah.chen@acme.example",
      "name": "Sarah Chen",
      "role": "Administrator"
    }
  }
}

A key that acts as the workspace reports "actsAs": { "type": "workspace" } with no other properties.

Response

Field	Type	Description
`status`	`string`	Always `ok`.
`teamId`	`string` (GUID)	Your workspace's key.
`teamName`	`string`	Your workspace's name.
`region`	`string`	`US` or `EU` — the region your workspace's data is stored in. Use the matching base URL.
`isEnterprise`	`boolean`	Whether the workspace is on the Enterprise plan. The MCP server needs it; the REST API does not.
`apiKey.name`	`string`	The name the key was given on the Team page.
`apiKey.createdDateTime`	`string`	When the key was created.
`apiKey.expiresDateTime`	`string`	When the key expires. Absent for a key that never expires.
`apiKey.actsAs.type`	`string`	`member` or `workspace`.
`apiKey.actsAs.id`	`integer`	The member's id — the same id Members reports. Absent for the workspace.
`apiKey.actsAs.email`	`string`	The member's email address. Absent for the workspace.
`apiKey.actsAs.name`	`string`	The member's full name. Absent for the workspace.
`apiKey.actsAs.role`	`string`	`Administrator` or `Member`. Absent for the workspace.

Notes

This call is charged to the cheap rate limit budget, so checking a key costs almost nothing. See Rate Limits.

Authentication Errors

Status	Code	When	What to do
`401`	`MISSING_API_KEY`	The `X-API-KEY` header is missing or empty.	Send the header.
`401`	`INVALID_API_KEY`	No workspace has this key.	Check for a typo or a stray space; copy the key again from the Team page.
`401`	`API_KEY_REVOKED`	An Administrator revoked the key. The message gives the date.	Ask an Administrator for a new key.
`401`	`API_KEY_EXPIRED`	The key has passed its expiry date. The message gives the date.	Ask an Administrator to extend it or create a new one.
`401`	`API_KEY_ACTOR_UNAVAILABLE`	The member the key acts as has been deactivated, removed or made a Guest.	Ask an Administrator to change who the key acts as.
`403`	`API_KEY_ACTS_AS_WORKSPACE`	A key that acts as the workspace was used on a route about a person.	Use a key that acts as a member.
`421`	`WRONG_REGION`	The key belongs to a workspace in the other region.	Resend the request to the address in the error's `url`.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests with an invalid key from your address, or the workspace's budget is spent.	Wait for `Retry-After` seconds. Fix the key first if it was invalid.

Invalid, revoked and expired keys are also throttled per source address: after 20 such refusals from one address inside a minute, further requests from it are answered 429 before the key is checked. A correctly configured integration never meets this limit.

Regions

CheckFlow stores each workspace's data in one region, and each region's API is served from its own address so that data, files and background work stay in that region.

Region	REST API	MCP server
`US`	`https://api.checkflow.io/v3/...`	`https://api.checkflow.io/mcp`
`EU`	`https://api-eu.checkflow.io/v3/...`	`https://api-eu.checkflow.io/mcp`

A key sent to the wrong region's address is refused before any data is read, with 421 Misdirected Request:

{
  "error": {
    "code": "WRONG_REGION",
    "message": "This workspace is in the EU region, which is served by https://api-eu.checkflow.io. Send this request to https://api-eu.checkflow.io/v3/checklists?status=InProgress instead.",
    "requestId": "req_5b0f6c2e0d8a4b52a1c7e3f9d4a61b20",
    "url": "https://api-eu.checkflow.io/v3/checklists?status=InProgress"
  }
}

The API does not redirect you, because many HTTP clients do not repeat a request body when they follow a redirect. Store the correct base URL in your integration's configuration instead.

Getting Started — from a new key to a completed task in five requests.
Errors — the error body and every error code.
User Permissions — what a Member can be allowed to do, and so what a key acting as them can do.
MCP Server — the same keys connect an AI assistant.

Creating an API Key​

Who a Key Acts As​

What Acting as a Member Changes​

Keys That Act as the Workspace​

Routes That Need a Person​

When the Member Changes​

Test Your API Key​

Parameters​

Example​

Response​

Notes​

Authentication Errors​

Regions​

Related Pages​