Travel API authentication

Travel API authentication is session based. You exchange your credentials for a SessionId once, then send that id with every other request.

There is no separate API key. The SessionId returned by Authenticate/CreateSession is the credential you pass on each call. Guard it the way you would guard a password.

Get your credentials

Your account comes with three values:

Create a session

Send the three values to Authenticate/CreateSession. The response carries the SessionId.

Body parameters

curl -X POST https://api.hermeseus.com/api/Authenticate/CreateSession \
  -H "Content-Type: application/json" \
  -d '{
    "OfficeId": "OFC-4821",
    "UserName": "jane.doe",
    "Password": "your-password"
  }'

const res = await fetch("https://api.hermeseus.com/api/Authenticate/CreateSession", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    OfficeId: "OFC-4821",
    UserName: "jane.doe",
    Password: "your-password"
  })
});

const { SessionId } = await res.json();

import requests

res = requests.post(
    "https://api.hermeseus.com/api/Authenticate/CreateSession",
    json={
        "OfficeId": "OFC-4821",
        "UserName": "jane.doe",
        "Password": "your-password",
    },
)

session_id = res.json()["SessionId"]

Response fields

{
  "Success": true,
  "SessionId": "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
  "Error": null
}

Send the session with each request

Pass the SessionId on every protected endpoint. Put it in the JSON body on POST and PUT requests. Put it in the query string on GET requests. The API reads both.

# POST: SessionId in the body
curl -X POST https://api.hermeseus.com/api/Common/CreditBalance \
  -H "Content-Type: application/json" \
  -d '{ "SessionId": "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f" }'

# GET: SessionId in the query string
curl "https://api.hermeseus.com/api/Activity/v2/products?SessionId=8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f&per_page=20"

const sessionId = "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f";

// POST: SessionId in the body
await fetch("https://api.hermeseus.com/api/Common/CreditBalance", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ SessionId: sessionId })
});

// GET: SessionId in the query string
await fetch("https://api.hermeseus.com/api/Activity/v2/products?SessionId=" + sessionId + "&per_page=20");

session_id = "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f"

# POST: SessionId in the body
requests.post(
    "https://api.hermeseus.com/api/Common/CreditBalance",
    json={"SessionId": session_id},
)

# GET: SessionId in the query string
requests.get(
    "https://api.hermeseus.com/api/Activity/v2/products",
    params={"SessionId": session_id, "per_page": 20},
)

Session lifetime

A session expires after a period of inactivity. Each successful call extends it, so an active integration keeps the same SessionId. When a call returns Err0101001 or Err0101002, the session is gone. Create a new one and retry the request once.

Do not call CreateSession before every request. Authenticate once, cache the id, and reuse it until it expires.

End a session

To drop a session before it expires, call Authenticate/EndSession.

{ "SessionId": "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f" }

Access levels

Each endpoint requires a permission granted to your office. If your office is not allowed to call an endpoint, the request returns Err0101006. Ask your account manager to enable the permission. Every reference page lists the permission it needs under Access.

The v2 alias

You can authenticate at v2/Authenticate/CreateSession instead. It is the same operation and the same session store, so a SessionId from either path works everywhere. Pick one and stay consistent.

Common mistakes

• Shipping the password or SessionId in a browser or mobile app. Both belong on your server.
• Calling CreateSession on every request. Do it once and reuse the id.
• Putting the SessionId in the URL on a POST. Send it in the body.
• Not handling expiry. Catch Err0101001 and Err0101002, re-authenticate, retry once.

Authentication errors

For the full catalogue, see the errors reference.