Authentication

Overview

The KOOB API authenticates every request with an API key, designed for server-to-server integrations with our B2B hotel, experience, and trip booking platform.

For detailed information about all endpoints, request/response schemas, and additional authentication details, visit our complete API Reference.

API Key Authentication

API keys are provided by our commercial team and should be included in the X-API-Key header for all requests.

Usage

GET /api/v3/hotels
X-API-Key: your-api-key-here
Content-Type: application/json

Example Request

curl -X GET "https://api.koob.tech/api/v3/hotels" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

Organization Selection

TIP

Most API keys and accounts are linked to a single organization, which is used automatically — if that's you, skip this section.

When an API key or a user account is linked to several organizations, use the optional X-Organization-Id header to select which organization the request acts on. It accepts either a raw organization id (e.g. 123) or an encoded gid.

GET /api/v3/hotels
X-API-Key: your-api-key-here
X-Organization-Id: 123
Content-Type: application/json

• Single organization (the common case): the header can be omitted — that organization is used automatically.
• API key with multiple organizations: the header is required on endpoints that do not take a legacy organizationId / toOrganizationId parameter.
• User with multiple organizations (bearer token): without the header, the request acts as the user's first organization.
• Group member (bearer token) or API key on a group: a group bundles several organizations (one per country, for example). Without the header, or with the group's id, requests cover every organization in the group. A group owns nothing itself: creating a hotel, experience, booking, trip or folder, or moving one, must name one of its organizations with the header. An API key on a group is linked to that group alone.
• Legacy parameters: organizationId (DMC keys) and toOrganizationId (TO keys) keep working unchanged and take precedence on endpoints that support them.

Possible errors:

• 400 Bad Request (code INVALID_ORGANIZATION_ID_HEADER) — the header value is malformed, or conflicts with a legacy organizationId / toOrganizationId parameter.

• 400 Bad Request (code ORGANIZATION_REQUIRED) — a group member or group API key created or moved something without naming one of the group's organizations. details.organizations lists the choices; resend with one of their ids in X-Organization-Id:

  {
    "name": "BadRequestError",
    "message": "Choose one organization with the X-Organization-Id header",
    "code": "ORGANIZATION_REQUIRED",
    "details": {
      "organizations": [
        { "id": "…", "name": "Koob Thailand" },
        { "id": "…", "name": "Koob Vietnam" }
      ]
    }
  }

• 403 Forbidden (code OWNED_BY_OTHER_ORGANIZATION) — the resource belongs to another of your organizations than the one in X-Organization-Id (a sibling in your group, for example). details.organization names the owner; resend with its id in the header:

  {
    "name": "ForbiddenError",
    "message": "This belongs to Koob Vietnam: resend with X-Organization-Id 1294",
    "code": "OWNED_BY_OTHER_ORGANIZATION",
    "details": { "organization": { "id": "1294", "name": "Koob Vietnam" } }
  }

  A resource outside all your organizations stays a 404.

• 401 Invalid organization — the organization is not linked to your API key or account.

Security Recommendations

• Store your API key securely and never expose it in client-side code.
• Rotate your key through our commercial team if you suspect it has been compromised.
• Rotation and revocation take up to a minute to reach every server. Keep the old key working during that window, then stop using it.