Keys and scopes
How to create and revoke API keys, which scopes to pick and what data each key can read.
Every API request carries a key. You create your own keys in the Bookline portal, and each one reads the data you can see, limited to the scopes you give it when you create it.
Creating a key
Section titled “Creating a key”Keys are created in the portal, under Administration → API keys in the menu. The entry appears only if your account can read at least one customer.
- Click Create key, give it a name (for example, the tool that will use it), pick its scopes and an expiry.
- Copy the key right away. It starts with
bk_live_and is shown only once; Bookline stores only a hash and cannot show it again. - Store it in your tool’s secret store, never in code or a shared sheet.
| Rule | Value |
|---|---|
| Expiry options | No expiry, 90 days, 1 year (default: 1 year) |
| Live keys per user | 5 |
| Account keys (whole customer) | 10 per customer |
Revoking a key
Section titled “Revoking a key”To stop a key, click Revoke next to it, on the same API keys page.
A key is tied to the person who created it and follows that person’s current access. If your role changes or your account is deleted, the key stops working.
Scopes
Section titled “Scopes”Each key carries scopes that decide which routes it can call: <domain>:read to read a domain, <domain>:write to change it. You pick them when you create the key and they cannot change afterwards: if you need different ones, create a new key and revoke the old one. If you don’t pick any, the key gets metrics:read.
Each domain of the API has a read scope and, where the API can change it, a write scope:
| Domain | Read | Write | Routes |
|---|---|---|---|
| Metrics | metrics:read |
/v1/metrics/* |
|
| Venues | venues:read |
venues:write |
/v1/venues (the list also accepts metrics:read) |
| Calls | calls:read |
/v1/calls |
|
| Chats | chats:read |
/v1/chats |
|
| Bookings | bookings:read |
/v1/bookings |
|
| Contacts | contacts:read |
contacts:write |
/v1/contacts |
| Agents | bots:read |
bots:write |
/v1/agents |
| Knowledge bases | knowledge_bases:read |
knowledge_bases:write |
/v1/knowledge-bases |
| Notifications (campaigns) | notifications:read |
notifications:write |
/v1/campaigns |
| Phone numbers | numbers:read |
/v1/numbers |
|
| Integrations | integrations:read |
/v1/integrations |
|
| Users (team members) | users:read |
users:write |
/v1/users |
| Billing | billing:read |
/v1/billing/* |
Calling a route without its scope is 403 insufficient_scope. Every route and the scope it needs is listed in Endpoints.
Ticking a domain’s write scope ticks its read scope too, and a key with a write scope always reads that domain: changing something needs a read first (see Writing data). So a key with contacts:write reads your whole contact book, and one with users:write your whole team: both are personal data.
What each key reads
Section titled “What each key reads”Send the key in the apikey header on every request. Only /v1/docs and /v1/openapi.json work without a key.
apikey: bk_live_...A missing or unknown key gets 401 invalid_api_key. A key works only on /v1.
What a key reads is decided on every request from its owner’s current access in the portal:
| Your access | What the key reads | customer_id |
|---|---|---|
| One customer, whole customer | That customer | Optional |
| Several customers | Any of them | Required (400 customer_ambiguous without it) |
| Some venues of a customer | That customer, only those venues | Optional when it is your only customer |
| Account key | Its own customer | Optional; another customer is 403 |
| Only a customer’s activity | That customer’s metrics, calls and chats; nothing else | Optional when it is your only customer |
Naming a customer the key cannot read is 403 insufficient_scope.
What each key can change
Section titled “What each key can change”A key changes data only when it holds the domain’s write scope and its owner’s access in the portal allows the change: ADMIN, or the level of the action (CREATE, UPDATE or DELETE). Access to a customer’s activity only never writes. An account key writes what its scopes allow on its own customer. Team access has its own rules: see Team members.
Venue-restricted access
Section titled “Venue-restricted access”- Without
venue_ids, you get every venue you can see. - With
venue_ids, each id must be one you can see; otherwise 403insufficient_scope. GET /v1/venueslists the venues your key can read, with their ids.- Venues, metrics, calls, chats, bookings, agents and knowledge bases are narrowed to those venues and their agents.
- Contacts, campaigns, phone numbers, integrations, team members and billing belong to the whole customer: a venue-restricted key gets 403
insufficient_scopeon them, and so does creating a knowledge base.
Related
Section titled “Related”- Bookline API: getting started with your key.
- Endpoints: every route and its scope.
- Writing data: versions, retries and the write limit.
- Errors and rate limits: what each error code means.
