home > support > API > making a connection

Authenticating with TourCMS API

Connection concept

Operators will have one or more Channels in their account, with an API key for each Channel. Marketplace Agents will be connected to one or more Channels, but use a single API key for all Channels they connect with.

Operators will send their Channel ID any time they make an API call. For Travel Agents, most endpoints such as those returning details on a specific tour, or making viewing bookings will need to be called with the appropriate Channel ID (i.e. multiple Operators will have a Tour with ID 1, or a booking with ID 1234). There are some API endpoints, for example those allowing Marketplace Agents to search for tours or bookings across any connected Channel where a Channel ID is not required and technically will be sent as 0.

Authentication headers

Authentication is handled by passing in two special headers when making any request to the API:

• x-tourcms-date: The GMT date/time the request was generated
• Authorization: The text "TourCMS " and then three values separated by colons (Channel ID:Marketplace account ID:Signature)
  • Channel ID - Can be 0 if you are a Marketplace agent searching multiple accounts.
  • Marketplace Account ID - Your unique ID number, for Individual Operator accounts this should be left as 0
  • Signature - See "Signature Generation" section below.

Signature Generation

For a reference implementation please see the generate_signature function in the PHP Client Library or any of the other client libraries & sample code.

String to sign

First we build our string to sign, in the following format:

CHANNEL_ID/MARKETPLACE_ID/VERB/OUTBOUND_TIME/PATH

CHANNEL_ID should be replaced with the ID of the Channel we are connecting to, or in the case of some Marketplace Agent API calls such as those searching across multiple Channels it can be 0.

MARKETPLACE_ID should be 0 for any Tour Operators calling the API, Marketplace Agents can find their ID in their welcome email or by logging into the Agent Portal and checking the API Settings area.

VERB should be the HTTP method of the request in uppercase (GET | POST).

OUTBOUND_TIME should be replaced by the current unix timestamp, e.g. 1714034150, this must match the value sent in the x-tourcms-date header, e.g x-tourcms-date: Thu, 25 Apr 2024 08:35:50 GMT

PATH should be the path endpoint we are calling, including any querystring, e.g. rate_limit_status.xml.

Sample

Our full string then for Operator request checking our API endpoint for search tours on channel 3930 would be:

3930/0/GET/1714034150/c/tour/datesprices/dep/manage/search.xml?id=1

Signing the string

Generate a keyed hash value using the HMAC method with the sha256 algorithm using your TourCMS API key. This should then be base64 encoded.

Signing the above string with the API Key PASSWORD would give the signature vCeCd9BvuITbJEM0GcpwcwqJjJnA%2BPZHgHoEzK76NPk%3D meaning our final headers would be:

	x-tourcms-date: Thu, 25 Apr 2024 08:35:50 GMT
	Authorization: TourCMS 3930:0:vCeCd9BvuITbJEM0GcpwcwqJjJnA%2BPZHgHoEzK76NPk%3D
	Content-type: application/xml