Authentication

Authentication with the XClaim API takes place using a JWT, which needs to be regularly renewed, in order to satisfy security best practises.

Introduction to JWTs

You can read more about JWTs here https://jwt.io/.

Credentials for login

You should be provided an API key and password to use with the authentication flow, during your integration journey.

You can then use them in order to generate a string value for the Authorization header, as in the below pseudocode. It generates the credentials to be used, consisting of the base64 encoded string, which should contain the api key, a colon, and the password.

credentials = base64encode(api_key + ':' + password)

Get a JWT token endpoint

Here is an example of a successful request to obtain a new JWT.

Get new JWT

GET https://staging.api.xclaim.xcover.com/auth/jwt/token/programmatic-access

Gets a new JWT for programmatic access to the XPay API

Headers

Name	Type	Description
Authorization*	String	Basic {{credentials}}

200: OK JWT successfully generated

{
    // Response
}

401: Unauthorized Invalid user

{
    // Response
}

403: Forbidden Invalid credentials

{
    // Response
}

Response

HTTP 200

{
    "data": {
        "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJpc3MiOiJodHRwczpcL1wvc3RhZ2luZy5hcGkueHBheS54Y292ZXIuY29tXC9hdXRoXC9qd3RcL3Rva2VuXC9wcm9ncmFtbWF0aWMtYWNjZXNzIiwiaWF0IjoxNjc2NDQ2NTExLCJleHAiOjE2Nzc2NTYxMTEsIm5iZiI6MTY3NjQ0NjUxMSwianRpIjoiODVMaDVsTmpXcmw3VnZERCIsInN1YiI6IjVlNzgyZjFjLTg3ZDAtNGU2Ni05YWRhLWJmNzZiYmI5YzRlYiIsInBydiI6IjIzYmQ1Yzg5NDlmNjAwYWRiMzllNzAxYzQwMDg3MmRiN2E1OTc2ZjciLCJ1c2VyIjp7ImlkIjoiNWU3ODJmMWMtODdkMC00ZTY2LTlhZGEtYmY3NmJiYjljNGViIiwicHJpbWFyeVJvbGUiOiJwYXJ0bmVyIn0sImNvbnRleHQiOm51bGx9.cbUIOuNQja__bk21cwJxymL1qzIv6kkhplWNymYPyRJc269KpMK6dYtpcT-iP8TmR28iJYAxWleWrOQ33lVy2LI-TgUIVcHHtq9MDFY2Q66blZ9xY_ug0RUWtTEIqwp4ygIgAWqv9yqpB8Ke5pzUf3fOHxPalWXVxS7Zz5WfXmJVI3bf9bwzaLAVhKO6AGVO2Qz-6QAxR0uoTsZ45EUBFBxpFACZ2msGIyb_34BrT6hfPTMDHUrpX7jv-BTmyHn3SD5pYCTLw5xPHdOIdXf-lW6hgaP-qyk5-RQYSuC6VXDHrzOMZJqiinJhYti38GdCjPf4YrUC_siXND4RUBwawvTSKCqtvuNCVFHuzltopxIwzEm_XHAVBTR79zxBU1Eqw9z8XMNxC3PhPxBoccwyXw2KmIjL9J1i7JGk0JfhYj0Z8gvWpvIap0Zck14_RxaYWhxRjHqiW7TGYqMQTIftHUBsIiRkyti9fqzqeTR6KxZRPRU4YCu0ox2y7Guh9la0TNHbfu9NkOr-p3TA919jB_UMifOQNdx25mk3r6GZVvPTPveCqkcKVlHLolys5Kv9pDjM7TWd1acyOFjSwqdCk-hFAPJZbcjL0PJ4vA-Et6xgGHDGeh3TIhlVxobMUuFhchVH-ADSrohGhu8GbvDSX5yoB1PHHHs77bmxIgjBKxs",
        "tokenType": "bearer",
        "expiresIn": 20160
    }
}

The JWT to be used is the string in the data.jwt property of the response. The expiresIn response attribute is simply metadata, which contains the expiry window duration in minutes. You can further decode the JWT according to the relevant standards, in order to obtain more information - such as the exact expiry time.

Recommended workflow for authentication

By default, these JWTs have an expiry window of 14 days, and this is done purposely to satisfy both security and optimality. Our recommendation is to rotate them, within the expiry window.

We recommend that you set up an automated, scheduled process (for example, once weekly) which requests a new JWT using the above endpoint, and stores it within your application for use, in any subsequent request. If you do this, then the JWT which is used by your application will never expire, since it will always be renewed around a week before expiry. Additionally, this allows you to not have to conduct the login request as a pre-requisite for any other request (which would incur extra latency to the overall API journey), and rather automate it away from the rest of your integration logic.

There is nothing you need to do with old JWTs, they will expire automatically and will not be honoured after their 14 day window lapses.