Start
API keys and scopes
Secret keys for your server, publishable keys for your apps, and the scopes that limit what each key can do.
Two kinds of key
A secret key (bidi_sk_) lives on your server and can do everything its scopes allow. A publishable key (bidi_pk_) is made to sit inside a mobile app: it can only chat with the assistants it names.
| Key | Where it lives | What it can do |
|---|---|---|
bidi_sk_ | On your server only | Everything its scopes allow |
bidi_pk_ | Inside your app | Chat with the assistants it names, nothing else |
Create a key
- Open Settings > Developers > API keys in your dashboard. The API comes with the Team plan and up.
- Press Create a key, give it a label you will recognise ("Website backend") and choose its kind.
- Tick only the scopes the key needs. Optionally limit it to some assistants and give it an expiry date.
- Copy the key from the dialog. It is shown this once: bidi keeps only a hash of it.
A workspace holds up to 20 active keys. Revoking one takes effect on the next call, and the audit log records who made and revoked each key.
curl https://www.bidii.ai/api/v2/me \
-H "Authorization: Bearer bidi_sk_YOUR_KEY"Scopes
A key carries only the scopes you give it; a write scope includes its read scope. The reference names the scope each endpoint needs.
| Scope | Allows | Includes |
|---|---|---|
agents:read | Read agents | None |
agents:write | Update agents | agents:read |
chat | Chat with agents | None |
sources:write | Add and remove sources | agents:read |
conversations:read | Read conversations | None |
leads:read | Read leads | None |
leads:write | Update leads | leads:read |
contacts:read | Read contacts | None |
contacts:write | Create, update and delete contacts | contacts:read |
webhooks:read | List webhook endpoints | None |
webhooks:write | Subscribe and unsubscribe webhooks | webhooks:read |
usage:read | Read usage | None |
tickets:read | Read tickets | None |
tickets:write | Update tickets | tickets:read |
The publishable key, chat only
Anyone who unpacks an app can read what is inside it, so an app never carries a secret key. A publishable key starts with bidi_pk_ and reaches the Chat operations only: every other call answers 403 secret_key_required, /me included, whatever scopes the key was saved with. Its limits (60 requests and 20 chats a minute) count each calling address on its own, so one phone cannot spend everyone's minute, and your plan's monthly conversations still apply.
A conversation a publishable key starts is continued only with its conversation_token, which the first answer gives you (the SDKs keep it for you), so knowing a conversation id is not enough to read or continue it. Both SDKs refuse a bidi_sk_ key outright. Publishable keys are switched on per bidi server; where they are off, the dashboard offers secret keys only.
A key never reaches more than its maker
Owners and members who manage developer settings make keys. Each scope also needs the matching permission in the maker's own role: a member who cannot read analytics cannot make a key with usage:read, and one who cannot work the helpdesk cannot make a key with tickets:read.
The rule holds every time the key is used, not only when it is made. When the maker's role changes, the key does only what the new role allows (a call it no longer may make answers 403 maker_role_limit), and when the maker is kept to some agents, the key reaches only those. When the maker leaves the workspace or is removed from it, the keys they made are revoked (401 invalid_key), and a key whose maker's membership ended any other way stops as well (401 key_maker_left). A publishable key, which anyone can read in your app, answers invalid_key and insufficient_scope instead. GET /api/v2/me shows what the maker's role holds back now, and the workspace's Owner sees it for every key in Settings > Developers.
Keeping keys safe
- Keep secret keys in your server's environment or secret store, never in a web page, an app or a repository.
- Give each integration its own key with only the scopes it needs, so you can revoke one without touching the others.
- To rotate, create the new key, deploy it, then revoke the old one.
- A key limited to some assistants reaches only those assistants, their conversations, leads and contacts.