Authentication
API keys and app access tokens, the headers to send, and how to keep them safe.
Every call to /partner/v1 carries one credential. There are two kinds, and both call the same operations.
| API key | App access token | |
|---|---|---|
| Looks like | cbk_ followed by 40 characters | cbat_... |
| Made by | A hotel owner or admin on Settings → Partner API, or ChatBeds for your sandbox | Your server, by swapping an OAuth code or refresh token at /oauth/token |
| Lifetime | Until it is revoked | 1 hour. Refresh it with the refresh token (cbrt_..., 90 days) |
| Permissions | Everything at its property | Only the scopes the hotel allowed |
| Stops when | The hotel revokes it | It expires, you revoke it, the hotel disconnects the app, or ChatBeds suspends the app |
Sending a credential
Send it as a bearer token:
Authorization: Bearer cbk_...
Authorization: Bearer cbat_...API keys may also be sent in their own header:
X-Api-Key: cbk_...A missing, unknown, expired or revoked credential answers 401 with a WWW-Authenticate: Bearer header:
{
"detail": "A valid API key or access token is needed: Authorization: Bearer cbk_... or cbat_..."
}No uninstall event
ChatBeds doesn't send a webhook when a hotel disconnects your app. You find out from a 401 on your next call, and then from invalid_grant when you try to refresh.
One property per credential
A key or token belongs to exactly one property.
GET /metells you which one. See Identity.- Anything outside that property answers
404, as if it didn't exist. - Within the property you see every booking, whoever made it: the dashboard, WhatsApp, or another partner.
If a hotel group has several properties, each property gives you its own key or its own OAuth connection. Store credentials per property.
Other refusals
| Status | When |
|---|---|
403 | An app token lacks the scope the operation needs, or the hotel's ChatBeds account is not active |
429 | Too many calls for this key, or too many calls with bad keys from your address. See Rate limits |
503 | ChatBeds has paused the partner API for a short while. Retry after the Retry-After seconds |
Keep secrets on your server
API keys, client secrets (cbs_...), access and refresh tokens and webhook secrets (whsec_...) are all server-side secrets.
- Never put them in a browser, a mobile app or a public repository.
- Store them encrypted, one set per property.
- ChatBeds keeps only a hash of keys, secrets and tokens. It can't show them to you again: if one is lost, make a new one.
- Log the key's
prefix(for examplecbk_8iT8Ct0S) to tell keys apart, never the full value.
Which one to use
Use an app if more than one hotel will use your software: hotels connect it in a few clicks, see exactly what it may do, and can disconnect it at any time. Use a private key for a one-off integration with a single hotel. Start with Register an app.
Building something?