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

# Authentication

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

Every reseller request carries one header:

```bash theme={null}
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.

<Note>
  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.
</Note>

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:

```json theme={null}
{ "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.