---
title: Authorization
description: The permissions an API key holds, what each endpoint needs, and the error when a key can't.
url: https://anyrow.ai/docs/authorization
canonical_url: https://anyrow.ai/docs/authorization
last_updated: '2026-10-16'
---

# Authorization

[Authentication](/docs/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](/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](/docs/api) names its permission under its path
(**Requires `tables:read`**), and its Markdown says the same. The
[OpenAPI document](/docs/openapi.json) carries it too, as the scope of the `apiKey` security
requirement, so generated clients and agents can read it:

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

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

## Permissions

| Permission | Allows |
| :-- | :-- |
| [`columns:write`](#columnswrite) | Add, edit, reorder and remove a table's columns. |
| [`export:read`](#exportread) | Export a table's rows and download the files. |
| [`extract:write`](#extractwrite) | Run extractions and schema suggestions, which use your plan's credits. |
| [`rows:delete`](#rowsdelete) | Delete rows. |
| [`rows:read`](#rowsread) | List, read, filter and aggregate rows. |
| [`rows:write`](#rowswrite) | Create, edit and bulk-write rows. |
| [`tables:delete`](#tablesdelete) | Delete tables and their rows. |
| [`tables:read`](#tablesread) | List and read tables, their rows, batches, exports and downloads. |
| [`tables:write`](#tableswrite) | Create, edit, restore and duplicate tables; change their columns and rows. |
| [`webhooks:manage`](#webhooksmanage) | Create, 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.

- [`POST /v1/projects/{project_id}/extract`](/docs/api/extract/once): Extract data from text or file (JSON response)
- [`POST /v1/projects/{project_id}/extract-stream`](/docs/api/extract/stream): Extract data from text or file (SSE stream)
- [`POST /v1/projects/{project_id}/tables/{table_id}/extract`](/docs/api/extract/table-once): Extract into table (JSON response)
- [`POST /v1/projects/{project_id}/tables/{table_id}/extract-stream`](/docs/api/extract/table-stream): Extract into table (SSE stream)
- [`POST /v1/projects/{project_id}/suggest-schema`](/docs/api/schema/schema): Suggest schema from text or file (multipart)

### `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.

- [`DELETE /v1/projects/{project_id}/tables/{table_id}`](/docs/api/tables/delete): Delete table (soft, 72h grace)
- [`DELETE /v1/projects/{project_id}/tables/{table_id}/rows/{row_id}`](/docs/api/rows/delete): Delete row

### `tables:read`

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

- [`GET /v1/projects/{project_id}/tables`](/docs/api/tables/list): List tables
- [`GET /v1/projects/{project_id}/tables/{table_id}`](/docs/api/tables/retrieve): Get table
- [`GET /v1/projects/{project_id}/tables/{table_id}/columns/{col_id}/distinct`](/docs/api/columns/distinct): Get distinct column values
- [`GET /v1/projects/{project_id}/tables/{table_id}/rows`](/docs/api/rows/list): List rows
- [`GET /v1/projects/{project_id}/tables/{table_id}/rows/aggregate`](/docs/api/rows/aggregate): Aggregate column values
- [`GET /v1/projects/{project_id}/tables/{table_id}/rows/{row_id}`](/docs/api/rows/retrieve): Get row
- [`GET /v1/projects/{project_id}/tables/{table_id}/rows/{row_id}/source`](/docs/api/rows/source): The source file behind a row: download it, or open a PDF or image inline
- [`GET /v1/projects/{project_id}/batches`](/docs/api/batches/list): List batches
- [`GET /v1/projects/{project_id}/batches/{batch_id}`](/docs/api/batches/retrieve): Get batch
- [`GET /v1/projects/{project_id}/batches/{batch_id}/download/csv`](/docs/api/batches/download-csv): Download batch CSV
- [`GET /v1/projects/{project_id}/batches/{batch_id}/download/json`](/docs/api/batches/download-json): Download batch JSON
- [`GET /v1/projects/{project_id}/batches/{batch_id}/download/xlsx`](/docs/api/batches/download-xlsx): Download batch XLSX
- [`GET /v1/projects/{project_id}/exports/{export_id}`](/docs/api/export/retrieve): Get export status
- [`GET /v1/projects/{project_id}/tables/{table_id}/export`](/docs/api/export/export): Export table rows
- [`GET /v1/projects/{project_id}/table-templates`](/docs/api/table-templates/project-list): Browse table templates
- [`GET /v1/projects/{project_id}/table-templates/{template_id}`](/docs/api/table-templates/project-retrieve): Preview table template

### `tables:write`

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

- [`POST /v1/projects/{project_id}/tables`](/docs/api/tables/create): Create table
- [`PATCH /v1/projects/{project_id}/tables/{table_id}`](/docs/api/tables/update): Update table
- [`POST /v1/projects/{project_id}/tables/{table_id}/duplicate`](/docs/api/tables/duplicate): Duplicate table structure
- [`POST /v1/projects/{project_id}/tables/{table_id}/restore`](/docs/api/tables/restore): Restore deleted table
- [`POST /v1/projects/{project_id}/tables/{table_id}/columns`](/docs/api/columns/add): Add column
- [`PUT /v1/projects/{project_id}/tables/{table_id}/columns/order`](/docs/api/columns/reorder): Reorder columns
- [`PATCH /v1/projects/{project_id}/tables/{table_id}/columns/{col_id}`](/docs/api/columns/update): Update column
- [`DELETE /v1/projects/{project_id}/tables/{table_id}/columns/{col_id}`](/docs/api/columns/remove): Remove column
- [`POST /v1/projects/{project_id}/tables/{table_id}/rows`](/docs/api/rows/create): Create row
- [`POST /v1/projects/{project_id}/tables/{table_id}/rows/bulk`](/docs/api/rows/bulk): Bulk create/update/delete rows
- [`PATCH /v1/projects/{project_id}/tables/{table_id}/rows/{row_id}`](/docs/api/rows/update): Update row
- [`POST /v1/projects/{project_id}/table-templates/{template_id}/use`](/docs/api/table-templates/use): Create table from template

### `webhooks:manage`

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

- [`GET /v1/organizations/{organization_id}/webhooks`](/docs/api/webhooks/list): List webhooks
- [`POST /v1/organizations/{organization_id}/webhooks`](/docs/api/webhooks/create): Create webhook
- [`GET /v1/organizations/{organization_id}/webhooks/{id}`](/docs/api/webhooks/retrieve): Get webhook
- [`PATCH /v1/organizations/{organization_id}/webhooks/{id}`](/docs/api/webhooks/update): Update webhook
- [`DELETE /v1/organizations/{organization_id}/webhooks/{id}`](/docs/api/webhooks/delete): Delete webhook
- [`GET /v1/organizations/{organization_id}/webhooks/{id}/deliveries`](/docs/api/webhooks/deliveries): List webhook deliveries
- [`POST /v1/organizations/{organization_id}/webhooks/{id}/rotate-secret`](/docs/api/webhooks/rotate-secret): Rotate webhook secret
- [`POST /v1/organizations/{organization_id}/webhooks/{id}/test`](/docs/api/webhooks/test): Send test webhook

## When a key can't

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

```http
HTTP/1.1 403 Forbidden
content-type: application/json

{
  "error_key": "forbidden",
  "fields": {},
  "message": "Access forbidden",
  "status": 403,
  "status_key": "forbidden",
  "success": false
}
```

| Status | `error_key` | Cause | Fix |
| --: | :-- | :-- | :-- |
| 401 | `unauthorized` | No `Authorization` header, a key that doesn't exist, or one that expired or was revoked | Send a live key as `ApiKey <key>` |
| 403 | `forbidden` | The key lacks the endpoint's permission, belongs to another project, or the request comes from an IP the key doesn't allow | Use a key of this project that holds the permission |
| 403 | `org_suspended` | The organization's payment failed | Update 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](/docs/errors) for the full envelope.

## Recipes

| Job | Permissions |
| :-- | :-- |
| Read-only agent or dashboard | `tables:read` |
| Importer that extracts files into tables | `extract:write`, `tables:read` |
| Sync that writes rows from another system | `tables:read`, `tables:write` |
| Webhook setup in CI | `webhooks:manage` |
| Full automation | every permission it uses, listed above |
