Skip to content

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.

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.

  1. Click Create key, give it a name (for example, the tool that will use it), pick its scopes and an expiry.
  2. 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.
  3. 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

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.

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.

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.

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.

  • Without venue_ids, you get every venue you can see.
  • With venue_ids, each id must be one you can see; otherwise 403 insufficient_scope.
  • GET /v1/venues lists 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_scope on them, and so does creating a knowledge base.