The v3 API does not use a static API key. You exchange a client ID and secret for a short-lived access token, then send that token on every call. Once the token handling is in place you rarely think about it again, but getting it wrong is the most common reason a first v3 integration stalls before it has read a single record.

If you are not sure whether your project needs v3 at all, start with Which Bookboost API should I use?

How to set this up

Ask support for v3 credentials. Say what you are building and whether you are a hotel integrating your own systems or a partner acting on behalf of several hotels, because the two get different credentials.
Store the client ID and secret securely, in a secrets manager or environment variables rather than in your code or a shared document.
Build the token exchange described below, and cache the result.
Send the token on every request to the v3 base URL, https://cdp.bookboost.io/cdp/public/v3.

Getting a token

Send a POST request to the token endpoint with a JSON body containing your grant_type, client_id, and client_secret.

curl --request POST \
  https://cdp.bookboost.io/api/m2m/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

A successful response contains an access_token, a token_type of Bearer, and expires_in, which is the token's remaining life in seconds.

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 43200
}

Calling the API with the token

Send two headers on every request: an Authorization header whose value is the word Bearer, a space, and the access token, plus Accept: application/json.

curl \
  https://cdp.bookboost.io/cdp/public/v3/profile-lists \
  -H 'Authorization: Bearer THE_ACCESS_TOKEN' \
  -H 'Accept: application/json'

That request is a good first call to prove your setup works. It returns your profile lists, and it does not change any data.

Caching and refreshing the token

Tokens last 12 hours by default. Cache the token you receive and reuse it until it is close to expiring, then exchange your credentials for a new one.

Do not request a fresh token on every API call. It is slower, it doubles your request count, and it will bring you closer to your rate limit than the work you are actually doing.

A reasonable pattern is to refresh when the token has less than an hour of life left, rather than waiting for a request to fail. If you would rather react than predict, retry once on a 401 with a newly fetched token before treating it as a real failure.

Extra headers for partners

Some v3 callers send two more headers alongside the bearer token.

If you are a partner, such as a PMS or channel manager integrating on behalf of several hotels, you also send a connection key and secret pair, so that Bookboost knows which hotel you are acting for on each request.

If you are a hotel integrating your own systems, you do not need them. The token already identifies your organisation.

We will tell you which case you are in when we issue your credentials, so you do not have to work it out from the behaviour.

When the login fails silently

Bad credentials return a 401 with an empty body. This is deliberate, so that nobody can probe which half of a credential pair was wrong.

It does mean a failed login tells you nothing about the cause, so when you hit a silent 401, check every credential rather than only the token:

The client ID and secret, including trailing whitespace picked up when they were copied.
Whether you are sending the token from a stale cache after it expired.
Whether the Authorization header includes the word Bearer and a space before the token.
If you are a partner, the connection key and secret as well.

The real reason is recorded on our side. If you have checked all of the above, ask support and we can look up why a specific attempt was rejected.

How this differs from v1

The v1 API uses a long-lived API key sent as a bearer token, with nothing to exchange and nothing to refresh. See API keys for how those are issued and looked after.

curl \
  https://cdp.bookboost.io/api/v1/users-list \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

The two are separate credentials. A v1 API key will not authenticate a v3 request, and a v3 token will not authenticate a v1 request. If your project uses both APIs, you need both.

Getting help

Open Help at the bottom of the left menu and choose Talk to Us, or email support@bookboost.io. If you are stuck on a rejected login, tell us the client ID and roughly when you tried, and we can check what happened.

Authenticating with the v3 API