Hitelesítés — Bokko Docs

Áttekintés#

A Bokko Public API minden kérése Bearer token hitelesítést igényel. Az API kulcsot az Authorization fejlécben kell küldeni.

Authorization: Bearer bk_live_<key>

Minden kulcs egyetlen tenanthoz (szolgáltatóhoz) van kötve
A kulcsok explicit capability halmazzal rendelkeznek -- csak azokat a műveleteket engedik, amelyekre jogosultságot kaptak
A kulcs önmagában nem ad teljes hozzáférést: a capability-k és a tenant scope együttesen határozza meg a jogosultságot

Tipp

A Publikus REST API használatához és az API kulcsok kezeléséhez Bokko Pro előfizetés szükséges. Ingyenes vagy Starter csomag esetén a kérések 403 auth.plan_insufficient hibával elutasításra kerülnek.

Figyelmeztetés

Az API kulcsot soha ne használd kliensoldalon (böngésző, mobil app frontend). A kulcs szerver-szerver kommunikációra való. Kliensoldalon kikerülhet a felhasználóhoz, és visszaélés célpontja lehet.

API kulcs típusok#

Tipp

Az API kulcsot a Bokko dashboardon hozhatod létre az Integrációk → API kulcsok menüpontban. Részletes UI útmutató: Help: API kulcsok kezelése.

Típus	Leírás	Visszavonás
personal	Delegált felhasználói jogosultság. A kulcs a létrehozó felhasználó nevében jár.	Automatikusan visszavonódik, ha a felhasználó hozzáférése megszűnik.
integration	Független jogosultság. Nem kötődik felhasználóhoz, önállóan működik.	Csak manuális visszavonással vagy lejárattal.

Tipp

Automatizációkhoz és külön rendszerek integrálásakor az integration típust javasoljuk. Így a kulcs nem függ egyetlen felhasználó fiókállapotától sem.

Capability-k#

Capability	Leírás
`availability.read`	Search available slots
`booking.create`	Create a booking
`booking.read`	Read a booking
`booking.cancel`	Cancel a booking
`services.read`	List services
`staff.read`	List staff
`webhook.manage`	Manage webhook configuration (get, set, rotate-secret, delete)
`subscription.read`	Read subscription state (plan, quota, features)

A kulcsok capability-kkel rendelkeznek, amelyek meghatározzák, mely műveleteket végezhetik el. A capability-ket a kulcs létrehozásakor kell beállítani.

Tenant scope#

Az API kulcsok egyetlen szolgáltatóhoz (szalonhoz) vannak kötve. A tenant scope érvényesítése az alábbi módon történik:

Kötelező salonSlug paraméter:

POST /availability/search -- szabad időpontok lekérdezéséhez (request body-ban)
POST /bookings -- foglalás létrehozásához (request body-ban)
GET /bookings -- foglalások listázásához (query stringben)
GET /services -- szolgáltatások listázásához (query stringben)
GET /staff -- munkatársak listázásához (query stringben)
GET /webhooks/config, PUT /webhooks/config, DELETE /webhooks/config -- webhook konfiguráció kezeléséhez
POST /webhooks/config/rotate-secret -- webhook secret rotálásához
GET /webhooks/deliveries -- kézbesítési napló lekérdezéséhez

Nem kötelező (a kulcs + booking resource alapján érvényesítve):

GET /bookings/{bookingId}
GET /bookings/{bookingId}/events
POST /bookings/{bookingId}/cancel
GET /subscription (a kulcs tenantja önmagában meghatározza a szolgáltatót)

Ha a megadott salonSlug nem egyezik a kulcshoz rendelt tenanttal:

HTTP 403
{
  "error": {
    "code": "auth.scope_mismatch",
    "message": "A kulcs nem jogosult erre a szolgáltatóra."
  }
}

Figyelmeztetés

A rendszer szándékosan 403-at ad vissza 404 helyett, hogy megakadályozza a tenant ID-k felderítését (tenant enumeration védelem).

Idempotencia#

Write műveletek támogatják az Idempotency-Key fejlécet az ismételt küldés elleni védelemhez.

Tulajdonság	Érték
Fejléc	`Idempotency-Key`
Formátum	UUID v4
TTL	24 óra
Fingerprint	tenant scope + operationId + path params + kanonikus body

Működés:

Ugyanaz a kulcs + egyező fingerprint --> az eredeti válasz visszaadásra kerül (meta.idempotent: true)
Ugyanaz a kulcs + eltérő fingerprint --> 409 idempotency.payload_mismatch

Rate limiting#

Route group	Standard	Elevated	Egység
`catalog`	120	600	kérés / perc
`availability`	30	150	kérés / perc
`booking`	30	150	kérés / perc
`webhook`	10	50	kérés / perc
`subscription`	60	300	kérés / perc

Per-key, per-route-group korlátozás, 1 perces gördülő ablakkal
Túllépés esetén a válasz:

HTTP 429
Retry-After: 30

{
  "error": {
    "code": "rate_limit.exceeded",
    "message": "Túllépte a kérésmennyiséget.",
    "retryable": true,
    "details": {
      "retryAfterSeconds": 30
    }
  }
}

Kulcs életciklus#

Művelet	Leírás
Létrehozás	A Bokko dashboardon, a Beállítások > API kulcsok menüpontban.
Visszavonás	Azonnali érvénytelenítés. A visszavont kulccsal küldött kérések `401`-et kapnak.
Lejárat	Opcionális `expiresAt` mező. Lejárat után a kulcs automatikusan érvénytelen.

Kódpéldák#

cURL#

bash

curl -X GET "https://api.bokko.io/v1/services?salonSlug=pelda-szalon" \
  -H "Authorization: Bearer bk_live_abc123def456"

JavaScript (fetch)#

javascript

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

const data = await response.json();

Python (requests)#

python

import requests

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

data = response.json()

Tipp

A kódpéldákban használt bk_live_abc123def456 kulcs csak illusztráció. A saját kulcsodat a Bokko dashboard Beállítások > API kulcsok menüpontjában találod.