Hermeseus Docs
Legacy docs

HAPI v3 quickstart

HAPI v3 is a clean, resource-oriented REST API for flights, hotels, and activities. You authenticate once with your client credentials, receive a bearer access token, and send that token with every request.

Everything lives under one base URL:

https://api.hermeseus.com/v3/HAPI

There is a single base for both environments. Whether you are hitting the sandbox or live inventory is decided by which credential you use, not by the host. Test credentials start with cid_test_; live credentials start with cid_live_.

1. Get your credentials

Your account comes with an OAuth2 client:

ValueExampleDescription
client_idcid_test_9f3c81d24a5b4c6d9e0f1a2bPublic identifier for your client.
client_secretsk_test_…The secret. Store it server-side; it is shown once.

2. Get an access token

Exchange the credentials for a short-lived bearer token with the client-credentials grant.

POST/v3/HAPI/auth/tokens
curl -X POST https://api.hermeseus.com/v3/HAPI/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cid_test_9f3c81d24a5b4c6d9e0f1a2b",
    "client_secret": "sk_test_your_secret"
  }'
const res = await fetch("https://api.hermeseus.com/v3/HAPI/auth/tokens", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: "cid_test_9f3c81d24a5b4c6d9e0f1a2b",
    client_secret: "sk_test_your_secret"
  })
});

const { access_token } = await res.json();
import requests

res = requests.post(
    "https://api.hermeseus.com/v3/HAPI/auth/tokens",
    json={
        "grant_type": "client_credentials",
        "client_id": "cid_test_9f3c81d24a5b4c6d9e0f1a2b",
        "client_secret": "sk_test_your_secret",
    },
)

access_token = res.json()["access_token"]

The response carries the token and its lifetime:

{
  "access_token": "hat_test_OJ5zqfaOpqsd9NmDisioHBQr1A4UTu56…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-08-27T17:36:36+00:00",
  "scope": "flights:read flights:write hotels:read hotels:write activities:read activities:write wallet:read",
  "environment": "test"
}

3. Send an authenticated request

Put the token in the Authorization header as a bearer credential. Every endpoint except the token endpoint expects it. Here we introspect the token to confirm who we are:

GET/v3/HAPI/auth/introspect
curl https://api.hermeseus.com/v3/HAPI/auth/introspect \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "active": true,
  "client_id": "cid_test_9f3c81d24a5b4c6d9e0f1a2b",
  "environment": "test",
  "office": { "id": "off_2", "name": "Your Office (sandbox)" },
  "scopes": ["flights:read", "flights:write", "wallet:read"],
  "token_type": "Bearer",
  "expires_at": "2026-08-27T17:36:36+00:00"
}
Tokens are short-lived. An access token lives for one hour. When it expires, requests return 401 expired_token; request a new one and retry. Cache the token and reuse it until it is close to expiry rather than minting one per call.

Next steps

You now have the one pattern every endpoint follows: get a token, then send it as a bearer. From here: