Securely access our APIs

Nationwide Platforms APIs use an OAuth 2.0 compliant protocol for authentication and authorization.

In order to obtain an access token, you will need to use the client id and client secret we provided you during the new user registration process.

⚠️ KEEP THESE CREDENTIALS SAFE AND STORED IN A CONTROLLED ENVIRONMENT ⚠️

All API calls will require a valid access token to be present in the “Authorization” header of the request.

This guide will show you have to obtain and use an access token with our APIs.

Step 1: Prepare

Before you can get the token, you will need to get the client id and client secret. This will be emailed to you after the creation of your API Developer Account. If you don’t have a user account, click on the “Sign up” link and fill in the form.

The next step is to understand the HTTPS request you will be making to get an access token. We have documented this API request and you can find the specification by clicking this link.

Step 2: Obtain access token

You will need to make a standard HTTPS Request to our API to obtain an access token. We will use the Postman app to make this API call. You can follow this link, click the green “Try” button and it will give you examples of making this API call in various programming languages such as C#.

HTTP Method: POST

URL: https://api.nationwideplatforms.co.uk/api/v1/token

Headers:

"Content-Type": "application/json"

Request Body:

{
  "clientId": "YOUR_CLIENT_ID_GOES_HERE ",
  "clientSecret": "YOUR_CLIENT_SECRET_GOES_HERE"
}

Responses:

HTTP STATUS 200 - OK – You will receive a JSON response containing your token.

{
  "token_type": "Bearer",
  "expires_in": 123,
  "ext_expires_in": 123,
  "access_token":"YOUR_ACCESS_TOKEN_VALUE_HERE"
}

HTTP STATUS 400 - BAD REQUEST – If a required field is missing from the request.

HTTP STATUS 401 - UNAUTHORIZED – If your credentials are invalid. 

Step 3: Using the access token

In order to interact with our APIs and make successful requests you will need to include the access token as an “Authorization” header and include the subscription key with the headers.

Guide on obtaining/viewing a subscription key can be found here.

Example of a REST API call to one of our APIs

HTTP Method: GET

URL: https://api.nationwideplatforms.co.uk/manage-hire-orders/awaiting-collection/api/v1/manage-hire-orders/awaiting-collection/awaiting-collection

Headers:

"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"

"Lox-Subscription-Key": "29212iSNDuWN2"

Responses:

HTTP 200 OK – You will receive a JSON response with machines awaiting collection.

HTTP 400 BAD REQUEST – If a required field is missing from the request.

HTTP 401 UNAUTHORIZED – If your credentials are invalid. 

Refresh the access token

Our access tokens have a limited lifetime, and this is expressed in the "expires_in" property as seconds. You will need to obtain a new token if yours has expired as old tokens will not be accepted by our services.

Changing the Client Secret

We do not have a self-service functionality to change/reset the client secret. We generate this when we send you the welcome emails.

Contact us immediately if you need to change this secret. We can issue you a new client secret and disable the previous one.