> ## 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 a key is refused.

Every call to the Partner API carries a partner key in the `Authorization` header.

```bash theme={null}
curl https://api.impellabs.tech/api/v1/partner/tenants/ \
  -H "Authorization: Bearer implpk_AB12CD34.YOUR_SECRET"
```

A key has two parts: a prefix that starts with `implpk_`, a dot, and a secret. The key belongs to your partner account,
not to a user. Every call resolves to your partner account, and a tenant of another partner answers 404.

## Keys are for servers

A request that carries an `Origin` header is refused with 403. A browser sends that header, so a key in a browser page
never works. Keep the key on your server.

## Create and revoke keys

You create and revoke keys with a partner console session, not with a key. A key that could make keys would outlive its
own revocation. A call to the key routes with a key answers 403.

| Call | Use |
| - | - |
| `GET /api/v1/partner/keys/` | List the keys: name, prefix, scopes, status, expiry and last use. |
| `POST /api/v1/partner/keys/` | Create a key. Send `name`, and optionally `scopes` and `expires_at`. |
| `POST /api/v1/partner/keys/{key_id}/revoke/` | Switch a key off at once. |

The answer to the create call holds the whole key once, in `key`. No other call shows it again. A key has the status
`active`, `expired` or `revoked`.

## Scopes

A key can call only the routes that its scopes allow. A call without the scope answers 403 with
`This API key does not have the "<scope>" scope.`

| Scope | Allows |
| - | - |
| `tenants:write` | Create, read, change and offboard tenants. |
| `channels:read` | Read channels, numbers, Pages, health checks and templates. |
| `channels:write` | Connect, change and disconnect channels. Switch numbers and Pages on or off. Change templates. |
| `messages:read` | Read conversations, messages and files. |
| `messages:write` | Send messages, take over and give back conversations, mark as read, show typing. |
| `assistants:write` | Give a conversation back to the agent with the resume call. |
| `webhooks:read` | List webhook endpoints and deliveries. |
| `webhooks:manage` | Create, change, rotate and delete webhook endpoints. |

A key can also hold `assistants:read`, `knowledge:read`, `knowledge:write`, `leads:read`, `leads:write`, `tools:write` and
`usage:read`. No route in this reference needs them. `leads:read` and `knowledge:read` decide which events an endpoint
hears. See [Webhooks and events](https://docs.impellabs.tech/partners/webhooks.md).

A webhook endpoint never hears more than the key that created it could read.

## Errors

| Status | Cause |
| - | - |
| 401 | The key is missing, wrong, revoked or expired. |
| 403 | The key lacks the scope, the request has an `Origin` header, or your partner account is suspended. |

See [Conventions](https://docs.impellabs.tech/partners/conventions.md) for the shape of an error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.