Authentication

Access is granted through a partner account defined by HMS. A partner account receives an apiKey and apiSecret, and HMS authorises which hotels it may access. The login endpoint exchanges these credentials for a hotel-bound token.

Login and token#

Request
POST /external/public/login HTTP/1.1
Host: test.hms.gen.tr
Content-Type: application/x-www-form-urlencoded

apiKey=5y94tLmALIKDyUVdEPlAAjg5xWGQNgQtnALlV4%2BAm7Q%3D&apiSecret=a143d640…&hotelCode=1000
Response · 200
{
    "success": true,
    "hotelCode": "1000",
    "token": "eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…",
    "hotelSeoUrl": "demo-otel"
}
FieldDescription
apiKeyPartner key. Contains base64 characters, so it must be URL-encoded in a form body (+ → %2B, = → %3D). HTTP libraries do this for you.
apiSecretSecret key. Keep it server-side only; never ship it in a browser or mobile app.
hotelCodeThe hotel’s HMS ID. If the partner is not authorised for the hotel, hotel_permission_is_not_found is returned.
hotelSeoUrlThe hotel’s SEO slug. Used instead of hotelCode only by HMS’s own booking engine; third-party integrations send hotelCode.

Bearer header#

Every endpoint except login expects the token in the Authorization header:

Request
GET /external/currencies HTTP/1.1
Host: test.hms.gen.tr
Authorization: Bearer eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…

If the header is missing, malformed (no Bearer prefix) or the token is unknown, the API returns 401:

401 Unauthorized
{
    "success": false,
    "error": "Authentication required"
}

Token lifetime and renewal#

  • The token is valid for 7 days. Renew it by logging in again before it expires; login is cheap and can be repeated for the same hotel.
  • Do not parse the token. Although it is a base64-encoded structure, its format is not guaranteed; store and forward it as an opaque string.
  • On a 401, log in once more and retry the request; a second 401 means the key pair or hotel authorisation has changed.

Hotel context#

A token is bound to a single hotel. The hotelID parameter on the endpoints must match that hotel; requesting another hotel yields an authorisation error or empty results. For multi-hotel integrations, obtain a separate token per hotel and cache it per hotel.

Login errors#

messageMeaning
partner_is_not_foundThe apiKey / apiSecret pair did not match. Check the keys and URL encoding.
hotel_is_not_foundNo hotel matched hotelSeoUrl.
hotel_permission_is_not_foundThe partner is not authorised for this hotel, or the authorisation is inactive. Contact HMS support.

These errors come back as HTTP 200 with success: false and token: null.

Last updated: 8 September 2026Found a mistake? Let us know