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
"clientId": "YOUR_CLIENT_ID_GOES_HERE ",
HTTP STATUS 200 - OK – You will receive a JSON response containing your token.
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.
Example of a REST API call to one of our APIs
HTTP Method: GET
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
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.