Authentication

All authenticated endpoints take a bearer token:

Authorization: Bearer <token>

There are two ways to get one, and which you want depends on whether a person or a machine is calling. 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’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 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:

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 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:

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:

POST /v1/connections/data/{connection_id}/resources
POST /v1/query-executions
POST /v1/assets/{asset_id}/previews

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.

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.

Introduction

Resources

Endpoints

Machine-to-machine (automation)

Scopes

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

Some `GET`s need `tables:append`

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

​Device login (people)

​Machine-to-machine (automation)

​Scopes

​File imports are agent:write, not tables:append

​Some GETs need tables:append

​Some POSTs need only agent:read

Device login (people)

Machine-to-machine (automation)

Scopes

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

Some `GET`s need `tables:append`

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