Authentication

Partner keys, scopes, and how to keep them safe.

Every reseller request carries one header:

Authorization: Bearer tgpk_a1b2c3d4e5f6.<secret>

A partner key is scoped to you, not to one business. It can reach every tenant in your workspace and nothing outside it.

Getting a key

Keys are minted from the reseller console, under API keys. They cannot be minted with an API key.

That restriction is deliberate. A key that can mint keys survives its own revocation: whoever held a leaked token would issue themselves a replacement before you noticed, and could revoke your real keys on the way out. Minting is a signed-in, human act.

The secret is shown once, at creation. We store a hash and cannot recover it. If you lose it, revoke it and mint another.

Never send it from a browser

The API rejects any partner key that arrives with an Origin header, because a browser is the one client that always sends one. Keep it in your backend’s secret store.

Scopes

A key only reaches what it was granted. Grant the minimum a caller needs — then a leaked key is a smaller problem.

Scope	What it unlocks
tenants:write	Provision, list, suspend and offboard businesses
knowledge:read	List cards, folders and documents
knowledge:write	Sync policies, upload documents, start crawls
assistants:read	List a tenant’s assistants
assistants:write	Create, configure and activate assistants
tools:write	Register MCP servers and enable their tools
channels:write	Set up the website widget
usage:read	Read per-tenant spend and your ceiling

A request outside a key’s scopes returns 403 with the missing scope named:

{ "detail": "This API key is missing the \"knowledge:write\" scope." }

Expiry and rotation

A key can carry an expiry, and is otherwise valid until revoked. To rotate without downtime: mint the new key, deploy it, confirm traffic has moved (the console shows last used per key), then revoke the old one.