Scopes
The permissions you give an API key or a connected app, and what each one allows.
A scope is one thing a key or a connected app is allowed to do. You choose them when you create a key, or when you approve an app like Claude.ai. Whatever you tick, it never goes beyond what you can do yourself in Cheqq.
Every scope
| Scope | In Cheqq it reads | What it allows |
|---|---|---|
records:read | See records | Read, count and summarize the records in your collections. |
records:write | Add and change records | Add records and change their values, one at a time or up to 200 at once. |
records:delete | Delete records | Move records to the Wapp's Trash. |
structure:read | See collections, fields, views and dashboards | List your Wapps and read how they're set up. |
structure:write | Change collections, fields, views and dashboards | Create, rename and delete collections; add, change and remove fields; create and change views and dashboards. |
workflows:read | See automations and their runs | Read automations, their runs, and the actions a step can use. |
workflows:write | Build and change automations — including steps that run code, call other services and send email on your behalf | Build automations, change them, replace their definition and move them to the Trash. An automation runs as you, with your connected accounts, so this includes steps that run code, call other services and send email, and triggers that start them on their own. |
workflows:run | Run and stop automations | Start runs (including test runs) and stop them. |
workflows:approve | Answer approval requests on your behalf | Approve or decline a run waiting for you, and let an automation stop asking. Never in a new key's starting set, so a key that runs automations can't also approve them. |
documents:read | Read documents | List documents and read their files and versions. |
documents:write | Create and edit documents | Create documents, save edits as new versions, and restore an earlier version. |
documents:delete | Delete documents | Move documents you own to Trash, where you can restore them in Cheqq for 30 days. A published one's public link stops working. |
apps:read | See Apps and their code | List your Apps, read their source, checkpoints and deploys. |
apps:write | Edit, check and test App code | Change an App's source and packages, restore a checkpoint, and check or verify the draft. |
apps:publish | Publish, unpublish and roll back Apps | Change what visitors see: publish the draft, take an App offline, or roll back to an earlier version. |
GET /me (and the cheqq_whoami tool) works with any scope, so a key can
always tell you what it's allowed to do.
What a new key starts with
Every :read scope, plus records:write and workflows:run. That lets a key
look at everything, keep records up to date and run your automations, but not
delete anything, reshape a Wapp, build automations, edit documents or Apps, or
publish.
An app you connect by signing in, such as Claude.ai, asks for what it needs and you approve it. When an app asks for everything, Cheqq ticks the same starting set and leaves the rest for you to opt into.
Apps register themselves with Cheqq, so the approval screen says when Cheqq hasn't verified an app and shows the full address your answer goes back to. For those apps, deleting, publishing, building automations and answering approvals always start unticked, even when the app asks for them; you can still tick them.
A key, or an app's access, works the same over the REST API and MCP: there's no separate permission for each.
Choosing scopes
- A report or a dashboard feed:
records:read, plusstructure:readto look up collections by name. - A sync that keeps records up to date:
records:readandrecords:write; addrecords:deleteonly if it should remove records. - An assistant that helps you build a Wapp: add
structure:write. - An assistant that builds automations:
workflows:read,workflows:writeandworkflows:run, so it can test what it builds. Addworkflows:approveonly if it should answer approvals for you. - An assistant that works on your site:
apps:readandapps:write. Addapps:publishonly if you want it to put changes live without you.
Delete and publish scopes act without asking you
Over the API and MCP, Cheqq's own Ask me first prompts don't appear:
there's nobody in Cheqq to answer them. An assistant asks you before a
destructive step only if your AI client is set to confirm tool calls. Give
records:delete, structure:write, workflows:write, workflows:approve,
documents:delete and apps:publish only to keys and apps you trust with
them. See
MCP tools.
Your role still applies
Scopes narrow what you can do; they never widen it.
- A Wapp you can only view stays read-only to every key.
- If you can only view the workspace, every key and app you connect there can only look, whatever was ticked.
- Some things are only yours: only a document's owner can delete it, and only the people an approval was put to can answer it.