JWT Tokens

Use JWT Tokens to authenticate web service calls.

Introduction

If you are using our JSON API, JWT tokens provide you with the most flexibility to hand out permission to use limited numbers of credits for specific services in specific time frames to individual users.

The Token Class

The JwTToken class should contain 3 claims: Token, CreditsRemaining and Expires such as the example below:

    public class JwtToken
    {
        public string Token { get; set; }
        public int CreditsRemaining { get; set; }
        public DateTime Expires { get; set; }
    }

Generating a Token

In order to give a JWT token to your user, you must first generate it with a server-side API call to the GetJWT method which is itself authenticated by username and password or server-side API key authentication.

This method takes all the restrictions that should be imposed on the token as parameters, such as when it will expire, how many credits it should be allowed to use and the IP address it can be used from, and returns the JWT token that has been generated. The application then needs to pass this token on to the client.

Using a Token

JWT tokens can only be used with our JSON API. They should be included in the Authorization header of the HTTP request and prefixed with the word Bearer, e.g.:

POST /AddressCapture/GetFullAddress.json
Content-Type: application/json
Content-Length: 103
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJEYXRhOCIsInN1YiI6Im1hcmtjIiwiZXhwIjoxNTQ2MjE0NDAwLCJjbiI6ImRhdGE4IGx0ZCIsImF1ZCI6IioiLCJtYyI6IjEwIiwianRpIjoiNjdkMGU1YmQtMmZmZi00M2ViLTk5YmEtYzA1Y2UzZjczY2FmIn0.UACICQSstufUC9AD7z2xYG3IGse9y92-8_L23_bUstw

The way you add this header will vary depending on the library you are using to generate your HTTP requests. For example, to make a request using the jQuery library you would use:

$.ajax("https://webservices.data-8.co.uk/EmailValidation/IsValid.json",
{
  method: "POST",
  headers: { Authorization: "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJEYXRhOCIsInN1YiI6Im1hcmtjIiwiZXhwIjoxNTQ2MjE0NDAwLCJjbiI6ImRhdGE4IGx0ZCIsImF1ZCI6IioiLCJtYyI6IjEwIiwianRpIjoiNjdkMGU1YmQtMmZmZi00M2ViLTk5YmEtYzA1Y2UzZjczY2FmIn0.UACICQSstufUC9AD7z2xYG3IGse9y92-8_L23_bUstw" },
  data: JSON.stringify({ email: "test@example.com" }),
  success: function(jqXhr) {
    // TODO: Handle the result here
  }
});