Authentication

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

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. 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 for the shape of an error.

Get started

Customers

Channels

Events

Partner API reference

Keys are for servers

Create and revoke keys

Scopes

Errors