Authentication

Overview#

Every request to the Bokko Public API requires Bearer token authentication. The API key must be sent in the Authorization header.

Authorization: Bearer bk_live_<key>

• Each key is tied to a single service provider business.
• Keys have an explicit set of capabilities -- they only allow operations they have been granted permissions for.
• The key alone does not grant full access: capabilities and the key's business scope together determine authorization.

API Key Types#

API Key Kinds#

In addition to the key type, Bokko v1 also uses a key kind to further restrict what an integration key may do.

For guest_partner keys, the allowed capability set is restricted to:

• services.read
• staff.read
• availability.read
• booking.create

Capabilities#

Keys have capabilities that define which operations they can perform. Capabilities must be configured when the key is created.

Business Scope#

API keys are tied to a single service provider business. This business scope is enforced in the following ways:

Mandatory salonSlug and locationSlug parameters:

• POST /availability/search -- query available slots (in request body)
• POST /bookings -- create a booking (in request body)
• GET /services -- list services (in query string)
• GET /staff -- list staff members (in query string)

Mandatory salonSlug parameter:

• GET /bookings -- list bookings (in query string)
• GET /webhooks/config, PUT /webhooks/config, DELETE /webhooks/config -- manage webhook configuration
• POST /webhooks/config/rotate-secret -- rotate webhook secret
• GET /webhooks/deliveries -- query delivery logs

Optional (validated based on key + booking resource):

• GET /bookings/{bookingId}
• GET /bookings/{bookingId}/events
• POST /bookings/{bookingId}/cancel
• GET /subscription (the key itself inherently determines the service provider business)

If the provided salonSlug does not match the service provider business assigned to the key, or the locationSlug is not found:

HTTP 403
{
  "error": {
    "code": "auth.scope_mismatch",
    "message": "The key is not authorized for this service provider or location."
  }
}

Idempotency#

Write operations support the Idempotency-Key header to protect against duplicate submissions.

Behavior:

• Same key + matching fingerprint --> the original response is returned (meta.idempotent: true)
• Same key + different fingerprint --> 409 idempotency.payload_mismatch

Rate Limiting#

The Bokko Public API applies a separate limit per route group and API key, with a 1-minute rolling window. There are two limit tiers: standard and elevated.

In case of exceeding the limit, the response is:

HTTP 429
Retry-After: 30

{
  "error": {
    "code": "rate_limit.exceeded",
    "message": "Rate limit exceeded.",
    "retryable": true,
    "details": {
      "retryAfterSeconds": 30
    }
  }
}

Key Lifecycle#

Code Examples#

cURL#

curl -X GET "https://api.bokko.io/v1/services?salonSlug=example-business&locationSlug=downtown" \
  -H "Authorization: Bearer bk_live_abc123def456"

JavaScript (fetch)#

const response = await fetch(
  'https://api.bokko.io/v1/services?salonSlug=example-business&locationSlug=downtown',
  {
    headers: {
      'Authorization': 'Bearer bk_live_abc123def456',
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();

Python (requests)#

import requests

response = requests.get(
    'https://api.bokko.io/v1/services',
    params={'salonSlug': 'example-business', 'locationSlug': 'downtown'},
    headers={
        'Authorization': 'Bearer bk_live_abc123def456',
        'Content-Type': 'application/json',
    },
)

data = response.json()