Authentication

Doing anything with the API requires authentication. The API will return a 401 Unauthorized for Unauthenticated clients.

The API uses tokens to authenticate every request. See the Token section below for more information.

Tokens

Applications that need to read or write information using the API are required to use Tokens.

Tokens provide two big features:

• Revokable access: users can revoke authorization to third party apps at any time

• Limited access: users can review the specific access that a token will provide before authorizing a third party app

The API requires two tokens to be passed with every call:

• Ocp-Apim-Subscription-Key: Subscription key which provides access to this API. Found in your Profile.

• TT-Api-Key: TruTac Api Token. See documentation for futher details.

The Ocp-Apim-Subscription-Key is provided upon request, whereas the TT-Api-Key can be created via the TruControl portal.

Hello World

Most applications will be wrapped in the language of your choice, but it's important to familiarize yourself with the underlying API HTTP methods first.

There's no easier way to get started than through cURL.

Let's test our setup. Open up a command prompt and enter the following command:

# POST /drivers/v1/api/drivers-search
curl POST "https://api.trulinks.co.uk/drivers/v1/api/drivers-search"
-H "TT-Api-Key: {TruTac Api Key}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"
--data-ascii "{}"

Which should return something like the following:

{
  "id": "123456-7890-1234-567890",
  "username": "harry.fellowes",
  "lastName": "FELLOWES",
  "firstName": "HARRY",
  ...
}

There's quite a lot going on in this one little call, so let's break it down. Firstly this is a POST call to the drivers-search API. The -H flag indicates we're adding a request header, you'll notice that we are adding two request headers, that's because every call to the API requires both a subscription key and an authentication key, see the Token section above for more information.

Ordinarily we would also submit some additional parameters in the request body. Here we are leaving the parameters blank by submitting --data-ascii "{}"

In this case the response is a list of Drivers.

Now that we've got the hang of making authenticated calls, let's move along to the APIs.