Authentication

Every call to the Cibusy API carries your venue's API key in the X-Api-Key header. The key decides which venues you reach and what you may do.

Sending the key#

Add the key to every request in the X-Api-Key header. Every call goes over HTTPS.

curl https://api.cibusy.com/public/v1/venues \
  -H "X-Api-Key: $CIBUSY_API_KEY"

Keys start with cbk_. The panel shows only the first characters of each key: enough to recognise it, not enough to make a request with.

Creating a key#

The venue's owner creates keys on the API Keys page of the Cibusy panel, signed in as the venue itself. Staff accounts cannot create keys.

• One key per integration. A key's name also appears on the orders it sends, so the venue can tell an order from its website from one sent by other software. Separate keys also let you revoke one without touching the others.
• Shown once. A key is shown only at the moment it is created. Cibusy keeps a hash of it, never the key itself, so a lost key cannot be recovered: it is revoked and replaced.
• Up to 10 keys. A venue can have 10 working keys at a time. To make room for a new one, revoke one you no longer use.

Permissions#

Every key has one permission; you turn on the other two, each on its own, when you create the key or later.

Change a key's permissions with Edit in the panel; the change applies from the key's next request. A call the key has no permission for is answered 403 PUBLIC_API_SCOPE_MISSING.

Give a key only what it needs. Turn on neither for a site that only shows your menu, and leave Can send orders off for a site that only takes reservations. Should the key ever fall into the wrong hands, it still cannot put an order in your kitchen.

Keep the key on your server#

The key is your venue's credential. Keep it in your server's configuration: an environment variable, or the secret manager you use. Never put it in a web page, a mobile app or a code repository.

Calls from a browser are not allowed. The API does not accept cross-origin (CORS) requests from other sites, and a key placed in a page can be copied by anyone who opens it. The right arrangement is:

Web page or app  →  your server (the key lives here)  →  api.cibusy.com

Your page or app calls your own server, and your server calls Cibusy with the key. This arrangement also makes it easy to keep a copy of the menu on your server.

Replacing a key#

To replace a key without an interruption:

1. Create a new key with the same permissions in the panel. If you use a webhook, enter its address on the new key too: each key has a signing secret of its own.
2. Put the new key and secret on your server and check that requests go out with the new key.
3. Revoke the old key with Revoke.

Each of a venue's keys can read the orders placed and the reservations taken with the venue's other keys, so you do not lose sight of them when you replace a key.

Revoking a key#

A revoked key stops working from its next request and cannot be turned back on. The orders it sent stay at the venue as they are.

• Every key of a venue that closes its account stops at once too.
• The Cibusy team can also revoke a key. The panel shows such a key as revoked.
• If you suspect a key has leaked, revoke it straight away and create a new one.

When the subscription lapses#

A key of a venue whose subscription has lapsed keeps reading the venue, its menu, its tables and its bookable times, as the QR menu does. Until the subscription is active again, orders are refused with 409 PUBLIC_API_ORDERING_UNAVAILABLE and reservations with 409 PUBLIC_API_RESERVATIONS_UNAVAILABLE.

Authentication errors#

A venue the key cannot reach is answered 404 PUBLIC_API_VENUE_NOT_FOUND; Venues and branches explains why.