GSTN Authentication Call

URL

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

The below example is provided for version: v1.0

The HTTP method required is: POST

The endpoint you shall be accessing is: <base_url>/gus/taxpayerapi/v1.0/authenticate

Headers

The headers will look somewhat like follows.

Name	Value
clientid	<your-client-id>
client-secret	<your-client-secret>
state-cd	<first-two-digits-of-your-gstin>
ip-usr	XXX.XXX.XXX.XXX
txn	<random-transaction-id>
Content-Type	application/json
X-Asp-Auth-Token	<your-X-Asp-Auth-Token>
X-Asp-Auth-Signature	<your-X-Asp-Auth-Signature>

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

To Understand how Request and Response payloads should be, refer to GST Developer Portal

The initial payload shall be like follows

{
    "action": "AUTHTOKEN",
    "username": "your_username",
    "app_key": "app_key_you_generated_for_this_request_encrypted_by_provided_public_key",
    "otp": "otp_sent_to_your_primary_credentials" 
}

The values for app_key will need to be encrypted using the public key. The resultant payload with encrypted values looks like follows.

Here is the example of encrypting your otp using your appkey in kotlin

You now need to encrypt the otp using the appkey that you received during the authentication handshake. An encrypted otp looks somewhat like `BmgX0cZuroBbOHk7KT4Wzw==```

{
  "action": "AUTHTOKEN",
  "username": "AkashSingh01",
  "app_key": "48Kw7zR3L9nsbBJI3BJBmg8K0cx/XoGzR6uJHcBCuEPUlBTDPLochguhJk1DTvvHYQqQwaU0yhOqfZHgalD9sGMikaEBmY7Y1YcjP5drvwhmmcqQmCLK3D1FE18ditvlqV4DWou5feLM07QwWTj/i8mDwc5YgWz0cYnr6r7wnd2nlbmMxdHOYbKjOP6SxOdD2Gb6GZDI5+RFkkfGSPKwtvXR9NfZQaLaTIY1w8O0X0NI56C9oqjcqT5+FgdpTnLYc3rodHJuEFVgqfeTpWSk3QfAcnQg9P1N9Azcx2OI+AXbLLhcLLbSpfveelhaK02uEdUDYgGHfztr//9RPfqOzg==",
  "otp": "BmgX0cZuroBbOHk7KT4Wzw=="
}

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

Response payload

{
  "status_cd": "1",
  "auth_token": "1ac094d572934070b193683054c1f5ba",
  "expiry": 120,
  "sek": "xyGEm6ZwaCK8m3A7gaQODOcb7cCYBOo/tqa6XTysvH+H3YvUBbtcgT4xd4qfCspP"
}

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 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.