API keys

Pass the key as a bearer token on every request. There is no session, no login call and no token exchange.

GET /v1/account HTTP/1.1
Authorization: Bearer vcb_live_7Kq2xY…
Accept: application/json

There is one way in and it is this header. An earlier version of this page also documented passing the key in a WebSocket subprotocol for a streaming endpoint at /v1/stream. That endpoint does not exist, so neither does that handshake.

Every key carries an explicit list of scopes, and every endpoint requires one. A key with no scope for a route is rejected before the request reaches any supplier.

Scopes are named <resource>:<action>. There is no generic read or write action — the actions are per resource, and these 11 are the complete list the gateway enforces, with every route each one opens:

The scopes actually granted to a key are shown on the key in the portal and returned by GET /v1/account. A rejected call names the one it was missing, so you never have to guess:

{
  "error": {
    "type": "insufficient_scope",
    "message": "The API key is missing the scope \"hotels:book\".",
    "requestId": "a4f1c358-6b2e-5acb-8ef5-0c3d0bcc35f5"
  }
}

Branch on insufficient_scope — that is the literal value; there is no missing_scope. requestId is a plain UUID with no prefix, and docUrl only appears when the deployment has a documentation base URL configured, so treat it as optional.

Grant the narrowest set that does the job — with one limitation worth designing around: reading a booking back needs the same …:book scope as creating or cancelling one. A reconciliation job that only reads therefore cannot be given a key that is unable to cancel. If that matters, keep the key on a system that cannot issue cancellations rather than expecting the scope to enforce it.

Each key can be pinned to a list of source addresses or CIDR ranges. A request from anywhere else is refused regardless of how valid the key is. This is the cheapest mitigation there is for a leaked credential, and it costs nothing if your egress addresses are stable.

Leave the list empty and the key is accepted from anywhere. A list that would allow everything is refused rather than stored, so say it by leaving the list empty.

If your egress is dynamic, an allow list is not the tool: keys have no expiry you can set at creation, so there are no short-lived keys to fall back on. Use a stable egress address, or leave the list empty and rely on keeping the secret out of reach.

Keys are stored as a SHA-256 hash. We cannot show you an existing secret, recover one, or read one out of a log — the plaintext exists exactly once, in the response that created it. Store it in your secret manager at that moment.

• Rotating a key issues a new secret and gives the old one an expiry in the near future, so both work while you roll out. Deploy the new secret, then let the old one lapse or revoke it early.
• Do not use the last-used timestamp to decide that traffic has moved. The field is shown in the portal but nothing updates it, so a key that is still serving live traffic looks unused. Confirm the cutover from your own side — your logs, or the X-Request-Id of calls you know you made with the new secret — before you revoke anything.
• Revocation is immediate: the gateway caches the key catalogue for 60 seconds but is invalidated on revoke, so a killed key stops working in under a second.
• Use separate keys per system — checkout, back office, batch jobs. One compromised component then costs you one rotation, not a coordinated one across your estate.
• Every key operation is recorded in an audit trail with the portal user who performed it. It is not exposed in the portal or over the API today, so if you need it for a compliance review, ask your Vacabee contact for an export rather than promising your auditor self-service access.

Your travellers do not have Vacabee accounts and never authenticate with us. There is no traveller resource on our side: we hold no per-traveller record you can address, and no identifier of yours is stored against one.

What does tie your records to ours is externalReference on each booking or order: your own value, echoed back, and the thing to quote in support. What we store per booking is what the supplier needs — guest or passenger names and the contact details you send. If a traveller exercises a deletion request, raise it with your Vacabee contact; there is no self-service endpoint for it today.