Authentication and scopes

Every operation on /api/v2/ is reachable with a machine credential and demands a scope, named on the operation as x-required-scope in the generated reference.

curl https://api.impellabs.tech/api/v2/responses \
  -H "Authorization: Bearer tgcc_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agt_...", "input": "Summarise the last quarter."}'

One key per workspace, identifying that workspace. Only a hash is stored, so the secret is shown exactly once — at creation — and no read path in the platform can reconstruct it. Keys carry an optional expiry, record their last use, and can be revoked individually.

Backend only. Never in a browser or a mobile client. Grant the minimum scopes a caller needs: that is the whole of what decides how bad an exposure is.The website widget uses a publishable key (tegain_site_…) which is meant to be public, is constrained by an origin allowlist and per-IP rate limits, and cannot read anything. It is not a workspace key and cannot call /api/v2/.

Scopes do not imply one another

There is no hierarchy, no wildcard and no implication. A key that may read conversations cannot run an agent. A key that may edit an assistant cannot preview its drafts. A key that may replay a webhook delivery cannot rotate its signing secret. A request outside a key’s scopes is 403 naming the missing scope. The endpoint is never silently skipped and never quietly narrows to nothing:

{
  "error": {
    "code": "permission_denied",
    "message": "This caller is not permitted to perform this operation.",
    "request_id": "req_..."
  }
}

The registry

adminapi/services/developer.py::SCOPES is canonical — a key cannot be created with a scope outside it, so a typo becomes a 400 rather than a key that silently authorises nothing. There are 42 entries. They are listed here in full, including the ones /api/v2/ never uses, because “what can this key do” should have one answer and not two.

The v2 runtime

Scope	Unlocks
`responses:create`	`POST /responses`, and `POST /responses/{id}/cancel`
`conversations:create`	`POST /conversations`
`conversations:read`	`GET /conversations/{id}`, `GET /conversations/{id}/messages`
`conversations:write`	`POST /conversations/{id}/messages`
`agents:run`	`POST /agents/{id}/runs`
`agents:read`	`GET /agents/{id}/runs/{run_id}`
`agent:preview`	`"preview": true` — running an agent’s unpublished configuration
`logs:read`	`GET /logs`, `GET /logs/{run_id}`

agent:preview is issued on its own and is implied by nothing. Asking for a preview is free; being allowed is not. Without the scope the answer is 404, not 403 — see Responses.logs:read is deliberately its own scope rather than a corner of usage:read (a billing figure) or chat:read (transcript content). It reads the shape of an execution — status, latency, model, tokens, tool names, error code — and a key that may debug an integration should not thereby read what that integration’s users said. There is no logs:write: nothing writes a log through an API.

Documents and intelligence

Scope	Unlocks
`documents:create`	`POST /documents`, `POST /documents/uploads`
`documents:read`	`GET /documents`, the content, representation and download-link endpoints
`documents:delete`	`DELETE /documents/{id}`
`extractions:create`	`POST /extractions`
`extractions:read`	`GET /extractions`, `GET /extractions/{id}`
`reports:create`	`POST /reports`
`reports:read`	`GET /reports`, `GET /reports/{id}`

Jobs

Scope	Unlocks
`jobs:create`	`POST /jobs`
`jobs:read`	`GET /jobs`, `GET /jobs/{job_id}`
`jobs:cancel`	`POST /jobs/{job_id}/cancel`

Read and cancel are split from create so a read-only monitoring integration cannot queue work.

Webhooks

Scope	Unlocks
`webhooks:read`	Endpoints, deliveries, events, the catalogue, settings
`webhooks:write`	Replaying a delivery or an event; regenerating the legacy workspace secret
`webhooks:manage`	Creating, editing and deleting an endpoint; rotating its signing secret

webhooks:manage is deliberately separate from webhooks:write. Creating an endpoint decides where a workspace’s events are sent, and rotating its secret decides who can forge them. That is a different authority from replaying a delivery — and it is the one an attacker actually wants.

Knowledge and the v1 platform surface

These predate v2 and are shared with /api/v1/. knowledge:read and knowledge:write are the two that /api/v2/knowledge/ingestions uses.

Scope	Unlocks
`knowledge:read` / `knowledge:write`	Cards, folders, documents, crawls — and v2 ingestions
`chat:read` / `chat:write`	Conversations on the v1 surface
`leads:read` / `leads:write`	Leads and lead lists
`assistants:read` / `assistants:write`	Assistant configuration
`tools:read` / `tools:write`	Tool servers and tool definitions
`calls:read` / `calls:write`	Calls
`bookings:read` / `bookings:write`	Bookings
`widgets:read` / `widgets:write`	Website widget configuration
`usage:read`	Metered usage totals

tools:read exists so that listing tools does not have to demand write. The write-only version failed closed but over-demanded, which teaches integrators to ask for more scope than they need.

Not issued on a workspace key

Three scopes are in the same registry but never granted to a customer key, because no customer surface declares them.

Scope	Held by
`tenants:write`	Reseller keys (`tgpk_`) — provisioning a tenant
`channels:write`	Reseller keys — connecting a tenant’s channels
`ops:inspect`, `ops:billing`	The internal ops console

The ops: pair is the second lock, never the first: every endpoint declaring one also demands a live staff operator record, which no machine credential has. Issuing one on a customer or partner key authorises nothing. They are in the registry at all because a declared scope no key could ever hold is a permanently locked door with a plausible-looking sign on it. tenants:write is coarse on purpose — a partner that can provision a tenant can already configure it, so splitting read from write there would be a distinction without a difference. See the Reseller API tab.

These docs say reseller; the marketing site says Partner API. They are the same product and the same tgpk_ credential. The URLs here stay /reseller/….

Two endpoints take no key at all

POST|PUT /documents/uploads/{token} and GET /documents/downloads/{token} are unauthenticated, and that is deliberate rather than an oversight. The signed token in the path is the credential: it names one upload or one document, for one purpose, inside one isolation boundary, for a bounded window — and it was minted only after a credentialed caller passed both the scope check and the credit gate. They are documented rather than hidden. Half a flow in a public document is worse than none: an integrator who can request an upload target and cannot find out what to do with it will guess. A grant is re-checked against the row on redemption, for something the signature cannot cover. A valid grant for a document that has since been deleted is a 404. A signature proves the link was issued; it does not prove the thing it points at still exists and is still yours.

What a workspace key does not reach

The ops console and the reseller console are separate surfaces and cannot be reached with a workspace key, whatever scopes it holds.

Get started

Runtime

Intelligence

Operations

Endpoint reference

agents

conversations

documents

extractions

jobs

knowledge

logs

reports

responses

webhooks

Scopes do not imply one another

The registry

The v2 runtime

Documents and intelligence

Jobs

Webhooks

Knowledge and the v1 platform surface

Not issued on a workspace key

Two endpoints take no key at all

What a workspace key does not reach

​Scopes do not imply one another

​The registry

​The v2 runtime

​Documents and intelligence

​Jobs

​Webhooks

​Knowledge and the v1 platform surface

​Not issued on a workspace key

​Two endpoints take no key at all

​What a workspace key does not reach

Scopes do not imply one another

The registry

The v2 runtime

Documents and intelligence

Jobs

Webhooks

Knowledge and the v1 platform surface

Not issued on a workspace key

Two endpoints take no key at all

What a workspace key does not reach