Get Started

Prerequisites

As described in the introduction, you will need credentials for two different authentication methods:

• A valid API key, which is used to identify the application consuming the Digital API
• New Skies agent credentials, used to operate with the different New Skies endpoints.

Also take in account that the production environment is guarded against unapproved IPs.

API Urls

2 different URLs for the New Skies Digital API are offered on the TUI backend:

Your first logon

Once you have all the prerequistes complete, you are ready for your first logon attempt.

The authentication scheme implemented in the Digital API requires that your API key is set in each request as a header field, x-apikey. The x-apikey can be found on the app you registered on the field CONSUMER KEY

The New Skies Digital API uses API keys as a simple identification layer. As such, OAuth tokens are not needed because the actual authentication is handled by the New Skies platform itself (see more details).

Notice that this only grants your application access to use the Digital API, but does not interact or is related to the New Skies sessions in any way. Therefore, the first request you need to perform is the authentication request against the Navitaire system. The received token is required on all further invoked requests.

Example Authentication Request

Please, find below an example of a request body for the token generation as well as an example on how to perform such a request using a bash console.

New Skies request token body payload

{
  "credentials": {
    "username": "YourUserName",
    "password": "YourPassword",
    "domain": "EXT"
  }
}

Setting the environment variables with your credentials

export X_API_XEY="yourApiKey"
export NEWSKIES_USERNAME="yourAgentName"
export NEWSKIES_PASSWORD="yourAgentPassword"

Curl Request to the Token endpoint to create a new session

curl --location "https://playground.api.tui/flight/newskies/rest/api/auth/v1/token/user" \
--header "Content-Type: application/json" \
--header "x-apikey: ${X_API_KEY}" \
--data "{
  \"credentials\": {
    \"username\": \"${NEWSKIES_USERNAME}\",
    \"password\": \"${NEWSKIES_PASSWORD}\",
    \"domain\": \"EXT\"
  }
}"

Example Response

{
    "data": {
        "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIzYjk4YWFmOC0zYjQ1LTQ0Y2UtOGI4Mi1hYjA3MTRjOGM3ZWUiLCJzZXNzaW9uSUQiOiIwIiwiYWdlbnRJRCI6Ijg0MDQzOSIsImRvbWFpbkNvZGUiOiJFWFQiLCJhZ2VudE5hbWUiOiJITFhCYXRjaE1hc3RlciIsIm9yZ2FuaXphdGlvbkNvZGUiOiJYMyIsInJvbGVDb2RlIjoiQUlSTSIsImNoYW5uZWxUeXBlIjoiRGlnaXRhbEFQSSIsInN5c3RlbVR5cGUiOiJVbmtub3duIiwiY2xpZW50TmFtZSI6IlVua25vd24iLCJjdWx0dXJlQ29kZSI6ImRlLURFIiwiY3VycmVuY3lDb2RlIjoiRVVSIiwibG9jYXRpb25Db2RlIjoiSFEiLCJwZXJzb25JRCI6Ijg2NzA4NSIsInBlcnNvblR5cGUiOiIyIiwidHJhY2VMZXZlbCI6IjAiLCJ0cmFjZVN3aXRjaGVzIjoiMCIsImFnZW50UXVldWVDb2RlIjoiIiwib3JnYW5pemF0aW9uUXVldWVDb2RlIjoiIiwiZXhwIjoxNzI2NDc2NDIxfQ.lIqGwl2JrEbPwEm5DqYDW8x4dzPKgzrtJibhQx2L36FOQ7IkAQMVyY8CI5TfEzNCQRkAvURlfHcvtgpJ8m4r_ASfE0qUIGKwGJ3TKhFZrqfkvrGf9D-ZbFd-Air0QfMH6azze3r62VD6huFKVHcYid6fL089LFwkRAK30hgtz34yrBXYWsSs9BC7Y85UTkc8XvhqwKExw6T2E8kwZ324wMKUvank0ic4f5EuKPvYgRe43xoD0QMzf-guWBq99_n6JE9PRZHYlnQNQmyCVkeS6SboL45NSygvusLsd4_dvNbNovBgD4G0Dd46pkStfHOTRrS_60XZ3YxsRpJATm3gaVnns1zPN7oa-6w4RS4dQG29aCv25J9kFCP4wiubu4AKWwjgt3zO7d9WSjPz3b4kH2rj7kHARiAmw_krMwsc2SyaQs-uUzeQ1psBqYjGvg5qlknmjwsrVYp1MyDS9R-hPzDckuCReiswQywTAcTPpDkyQc-EqEUb_QwXX6PdCDTI",
        "cultureCode": "de-DE",
        "currencyCode": "EUR",
        "roleCode": "AIRM",
        "locationCode": "HQ",
        "domainCode": "EXT",
        "organizationCode": "X3",
        "expires": "2024-09-16T08:47:01Z",
        "userKey": "ExampleUserKey",
        "personKey": "ExamplePersonKey"
    }
}

You need to extract the token string from the response as this is required on each further request. The received token must be provided on Authorization header. In summary, once the token is obtained from the endpoint, all subsequent requests should include the following headers:

Correlation-Id

A correlation-id is like a unique identifier or a tracking value (like a guid) used in APIs to trace and link all the related requests and responses in a system. Imagine you’re sending a package and you get a tracking number. This number helps you follow the package’s journey from start to finish. Similarly, a correlation-id helps developers track the flow of a request through different services and systems, making it easier to debug and monitor.

To make use of correlation-id, you can utilize the x-correlation-id header and provide any string value you like, for example:

curl --location 'https://playground.api.tui/flight/newskies/rest/api/auth/v1/token/user' \
--header 'Content-Type: application/json' \
--header 'x-apikey: {YourApigeeApiKey}' \
--header 'X-Correlation-Id: 54bfa520-4586-46a9-8409-e6a4ea402451'

Once you provide the same correlation-id within a unique workflow, we will be able to trace your workflow and troubleshoot more effectively.

Further reading

On the following pages, we will explain how to create bookings using our simple and advanced-workflow.