Developers

Authentication

Every request carries a Bearer key. Test keys are for building; live keys are for production and stay on your server.

Updated 2026-10-20

How do I authenticate?

Send your key in the Authorization header as Bearer <keyId>.<secret>: the public key id, a dot, then the secret.

curl

curl https://<your-booking-domain>/api/partner/v1/me \
  -H "Authorization: Bearer pk_test_AbC123dEf456GhI7.xxxxxxxxxxxxxxxx"

The only route without authentication is GET /health, a liveness check.

The secret is shown once

We show the secret a single time, when the key is issued, and store only a hash, so we cannot show it again. If you lose it, ask for a new key. Keep it in server-side configuration; never commit it or ship it in a web page or mobile app.

What is the difference between test and live keys?

	Test key	Live key
Prefix	`pk_test_`	`pk_live_`
Available	As soon as your account is enabled	Once the operator switches live access on for you
Before then	Works	Answers `403 SANDBOX_ONLY`
Catalogue and availability	Real, live data	Real, live data
Bookings	Practice bookings (`TST-` refs): no charge, no capacity held	Real bookings (`DR` refs)
Browser (CORS) calls	Yes, from your listed origins	No: server to server only

Call GET /me to see which mode a key is in (mode is test or live). A key only ever sees bookings created in its own mode: a test key never sees live bookings and a live key never sees sandbox ones.

Can I call the API from a browser?

Only with a test key, and only from the origins we have on your account. A secret used in a browser is visible to every visitor of that page, so live keys get no CORS headers at all. Build a small server-side proxy for production and keep your live key there.

Can I restrict which servers can use my key?

Yes. Ask us to set an IP allow-list on your account. Requests from any other address are refused with 403 FORBIDDEN, even with a valid key. Treat it as a second lock: the key is still the primary control.

How do I rotate a key?

Ask the operator to issue a new key (test or live). You receive a new id and a new one-time secret.
Deploy the new key to your server and confirm GET /me works with it.
Ask for the old key to be revoked. A revoked key answers 401 AUTHENTICATION from then on.

Rotate straight away if a secret may have leaked.

Which errors can authentication return?

Code	HTTP	When
`AUTHENTICATION`	401	The Authorization header is missing or malformed, the key id is unknown, the secret is wrong, or the key has been revoked.
`FORBIDDEN`	403	Your account or API access is disabled, the request came from an IP address that is not on your allow-list, or you asked for an experience that is not enabled for your account.
`SANDBOX_ONLY`	403	You used a live key (pk_live_) before live access was switched on. Use your test key.

json401

{
  "ok": false,
  "error": {
    "code": "AUTHENTICATION",
    "message": "This API key has been revoked."
  },
  "requestId": "req_41be07"
}

json403

{
  "ok": false,
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "Live access is not enabled yet — use your test key (pk_test_…)."
  },
  "requestId": "req_77c2d9"
}

Next: Catalog →