> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Get a bearer token for the Summation API: device login for people, machine-to-machine credentials for automation.

All authenticated endpoints take a bearer token:

```text theme={null}
Authorization: Bearer <token>
```

There are two ways to get one, and which you want depends on whether a person or a machine is calling.

## Device login (people)

An RFC 8628 device-authorization flow: request a device login, approve it in the browser, poll for the credential.

This is what the [Claude plugin](/integrations/claude-plugin)'s `/addison:login` and `sumcli login` do for you. If you're a person using an agent or a shell, use the plugin or [sumcli](/api/cli) rather than implementing the flow yourself.

## Machine-to-machine (automation)

Your Summation admin issues a `client_id` and `client_secret` with scopes. Exchange them for an access token:

```bash theme={null}
curl -X POST https://api.summation.com/v1/auth/m2m/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scope=agent:read agent:write"
```

The exchange is form-encoded; all other endpoints use JSON bodies. Access tokens expire (about an hour). Refresh by exchanging again.

For scripted work, prefer [sumcli](/api/cli) with an M2M profile: it manages the exchange and refresh for you.

## Scopes

Tokens carry scopes that gate access. A valid token missing a scope gets a `403` with the missing scope named.

| Scope           | Grants                                                                                |
| --------------- | ------------------------------------------------------------------------------------- |
| `agent:read`    | Reads: catalog, query, previews, file and report content                              |
| `agent:write`   | Mutations: report generation, playbooks, workflows, connections, **and file imports** |
| `tables:append` | Row appends, ingestion batches, source-sync pages, and SumApp register/deregister     |

The default rule is the HTTP method: **`GET` needs `agent:read`, everything else needs `agent:write`.** Identity endpoints (`/v1/me`, auth status, logout, org details) authenticate but require no scope at all.

Three sets of operations break that rule, and each one bites.

### File imports are `agent:write`, not `tables:append`

The name suggests otherwise, but every file-import operation enforces `agent:write`:

| Operation             | Route                                                    |
| --------------------- | -------------------------------------------------------- |
| `write_file_content`  | `PUT /v1/projects/{project_id}/files/content`            |
| `create_file_upload`  | `POST /v1/projects/{project_id}/files/uploads`           |
| `import_file`         | `POST /v1/projects/{project_id}/files/{file_id}/imports` |
| `create_table_import` | `POST /v1/table-imports`                                 |

`tables:append` will not open any of them.

### Some `GET`s need `tables:append`

`agent:read` is not enough for these: they sit inside the append surface, so a read-only token gets a `403`:

```text theme={null}
GET /v1/tables/{table_id}/ingestion-batches/{batch_id}
GET /v1/data-syncs/{sync_id}/checkpoint
GET /v1/data-syncs/{sync_id}/pages/{page_id}
```

### Some `POST`s need only `agent:read`

These are reads exposed over `POST` because they take a body. A read-only token is sufficient:

```text theme={null}
POST /v1/connections/data/{connection_id}/resources
POST /v1/query-executions
POST /v1/assets/{asset_id}/previews
```

<Note>
  The full `tables:append` set is: `POST`/`PUT /v1/tables/{table_id}/rows`, all five `/v1/tables/{table_id}/ingestion-batches` operations, the three `/v1/data-syncs/{sync_id}` operations, and `POST /v1/sum-apps` / `DELETE /v1/sum-apps/{slug}`. Everything else follows the method rule above.
</Note>

<Note>
  **Never paste a personal bearer token into client config.** For MCP clients, headerless registration plus browser approval is the supported path for people. See [MCP Server](/integrations/mcp-server).
</Note>