Skip to content

Using the API

Authorization

The permissions an API key holds, what each endpoint needs, and the error when a key can't.

Authentication proves who is calling. Authorization decides what that key may do: every API key belongs to one project and holds a set of permissions, and every endpoint needs one of them. A request succeeds only when the key's project matches the path and the key holds the endpoint's permission.

Get a key with the right permissions

  1. Open the project's API keys

    In the app, open the project and choose API keys.

  2. Choose its permissions

    Name the key after where it runs, then pick the permissions it needs from the list below and nothing more. A key for a nightly export needs tables:read; an importer that creates rows also needs tables:write.

  3. Use it

    Send it as Authorization: ApiKey <key>. To change what a key can do, create a new key with the permissions you want, deploy it, and revoke the old one.

What each endpoint needs

Each endpoint's page in the API reference names its permission under its path (Requires tables:read), and its Markdown says the same. The OpenAPI document carries it too, as the scope of the apiKey security requirement, so generated clients and agents can read it:

"security": [{ "apiKey": ["tables:read"] }]

An endpoint whose requirement lists no scope accepts any valid key of the project.

Permissions

PermissionAllows
columns:writeAdd, edit, reorder and remove a table's columns.
export:readExport a table's rows and download the files.
extract:writeRun extractions and schema suggestions, which use your plan's credits.
rows:deleteDelete rows.
rows:readList, read, filter and aggregate rows.
rows:writeCreate, edit and bulk-write rows.
tables:deleteDelete tables and their rows.
tables:readList and read tables, their rows, batches, exports and downloads.
tables:writeCreate, edit, restore and duplicate tables; change their columns and rows.
webhooks:manageCreate, edit, test and delete webhooks, and rotate their secrets.

columns:write

Add, edit, reorder and remove a table's columns.

No endpoint requires this permission yet.

export:read

Export a table's rows and download the files.

No endpoint requires this permission yet.

extract:write

Run extractions and schema suggestions, which use your plan's credits.

rows:delete

Delete rows.

No endpoint requires this permission yet.

rows:read

List, read, filter and aggregate rows.

No endpoint requires this permission yet.

rows:write

Create, edit and bulk-write rows.

No endpoint requires this permission yet.

tables:delete

Delete tables and their rows.

tables:read

List and read tables, their rows, batches, exports and downloads.

tables:write

Create, edit, restore and duplicate tables; change their columns and rows.

webhooks:manage

Create, edit, test and delete webhooks, and rotate their secrets.

When a key can't

A key without the endpoint's permission, or one from another project, gets a 403:

HTTP/1.1 403 Forbiddencontent-type: application/json{  "error_key": "forbidden",  "fields": {},  "message": "Access forbidden",  "status": 403,  "status_key": "forbidden",  "success": false}
Statuserror_keyCauseFix
401unauthorizedNo Authorization header, a key that doesn't exist, or one that expired or was revokedSend a live key as ApiKey <key>
403forbiddenThe key lacks the endpoint's permission, belongs to another project, or the request comes from an IP the key doesn't allowUse a key of this project that holds the permission
403org_suspendedThe organization's payment failedUpdate the payment method; vars.current_plan names the plan

A 401 has the same shape with "error_key": "unauthorized" and "message": "Authentication required". See Errors for the full envelope.

Recipes

JobPermissions
Read-only agent or dashboardtables:read
Importer that extracts files into tablesextract:write, tables:read
Sync that writes rows from another systemtables:read, tables:write
Webhook setup in CIwebhooks:manage
Full automationevery permission it uses, listed above