Skip to content

Authentication Call

URL#

Refer to API Ecosystem and NIC API document to form the correct URL.

The below example is provided for version: v1.04

The HTTP method required is: POST

The endpoint you shall be accessing is: <base_url>/gus/irp/{irp_provider}/eivital/v1.04/auth

Headers#

The headers will look somewhat like follows.

Name Value
gstin <your-GSTIN>
Content-Type application/json
X-Asp-Auth-Token <your-X-Asp-Auth-Token>
X-Asp-Auth-Signature <your-X-Asp-Auth-Signature>

Note: There are some headers that you should not populate. The GSP will populate them for you on the fly using the GSP credentials. These are

  • client-id

  • client-secret

  • einvoice-user-id

Also, note that the details of how to construct the X-Asp-Auth-Token is covered in greater details in Building a Vayana GSP Auth Token

Request Payload#

The initial payload shall be like follows

{
    "UserName":"testuser",
    "Password":" < Password in plain text >",
    "AppKey":" < Any random 32 bytes array, generated by user. On converting to String using base 64 encoding will be 44 chars long.>",
    "ForceRefreshAccessToken": true
}

Sample json file for initial payload 

{
    "UserName":"testuser",
    "Password":" abcde",
    "AppKey":" e1d65bgSeTrTatc7atLhKWyUbM/ekfbAWu2dFMfyNuYS+ ==",
    "ForceRefreshAccessToken": true
}

  • Above json payload need to convert into ByteArray.
  • Encode this ByteArray using Base64 Encoder.
  • Encrypt the encoded output using E-Invoice Public Key.
  • Note: Encoded output should be in ByteArray format.

The resultant payload with encrypted values looks like follows - 

{
  "Data": "amMy4UXLuG5878PuVK/4KkJdbLIH7H4U7v+uLfZFMWoRr5jWO0015IB8eFNsc305q9ziWlxkCiqOAiHRgm3KJRY5xGngHe7HFjxuVgpEDzrB6Q7wp3NGmRZH8WnfoZMg1h3GXJ3x+NOR+QnymnAnyjAtgtOz19JZgnhF3uwI7UNiH2QpG1r1HkVHSvuBbZfNkRYcUqCL0pThyQD09LXYStYPqEVHKoPSydJdHFlwzAxjBFYMCzpAUszUlrcdTN1DHCU3d/ZyrjFfc+j63dZz3xZoGNO5MAfT5pEVs4Mj5ccztNVqPc/Aw6xie+Dx+V/8kJDiUBqWHgYMl70JLZkC2A=="
}

This request has to be dispatched upon which you will get a response from the server that if all is successful will look somewhat like follows

Sample Response payload#

{
  "Status": 1,
  "Data": {
    "ClientId": "testclientid",
    "UserName": "testuser",
    "AuthToken": "5 GGo3hKqPSvbHwRImTjIxeMKQ",
    "Sek": "EmLpFzYohZLstcXCSX9C9XIHVLb+QcsjMO1mk+qAjW8hyXmEBQnCAYsmbluF Fu+Z",
    "TokenExpiry": "2019-11-30 14:18:00"
  },
  "ErrorDetails": null,
  "InfoDtls": " < alert message > "
}

The sek is returned to you encrypted by the app key you passed. You now have to decrypt it using the app key you generated and provided. In this particular case the decrypted value of the sek looks like 10fqSD37aTCzfYsxx2br0P8d0XFCtVC/SgcqHCO2rKQ=

Note: all the encrypted values will look totally different for you, but if the lengths don’t roughly match up, you know something is going wrong.

What you need to save#

The authentication here is usually valid for about 6 hours before you need to authenticate again.

Note: Since the userids to the test system might be shared, the six hours is the interval from the first authentication call - you may end up facing a situation where you have to re-authenticate much sooner.

Hence, some values used here are used for all future interactions for the duration of the authentication.

We suggest you store these values so that they can be used until your authentication token is valid. These values are

  • username and/or gstin: This is the username for which the following values have been generated
  • app_key: This was an app_key that you generated when making the API calls
  • authtoken: This was returned to you in the response payload
  • sek: This was returned to you in the response payload, albeit encrypted using the app_key that you had passed
  • created_on: This was the timestamp on which you made the authentication request. Since the validity is roughly six hours, we suggest you stop using this token once 5:45 hours have passed and re-do authentication again