Skip to content

Building a vayana gsp auth token#

In order to connect to Vayana GSP you will need to build a Vayana GSP auth token string and signature

Why “auth-string-and-signature” headers for authentication?#

VayanaGSP considered the following parameters while building the authentication scheme

  • Simplicity: Stuff for which sample code and examples are easily available

  • Based on known standards: Don’t invent your own wheel

  • Supportive of High performance stateless processing: e.g. Don’t go to the database with each API call. Helps both performance and cluster ability

  • Support for non repudiation: The mechanism should prevent any possibility by which the GSP can claim ASP usage maliciously.

  • Ease of key management for ASPs including for shared nothing architecture clients (PHP/Python/Ruby based) and across cluster nodes for multi instance ASPs

Building the basic token#

This is a colon delimited string that looks like follows.

v2.0:<cust_id>:<client_id>:<txn_id>:<timestamp>:<gstin>:<api_action>

The various fields in the sequence are as follows.

  • v2.0 - This is a constant field indicating the auth token version. Keep it exactly as is. No change

  • cust_id - Some of you will receive cust id from Vayana (and some others’ client id). If you receive a cust id, populate it here, keep the client id just an empty string.

  • client_id - Those of you who receive a client id should populate it here.

  • txn_id - This is a transaction id you generate referring to the particular transaction. It is recommended to be able to unique in order to identify a particular transaction.

  • timestamp - This is a timestamp. It is of the format YYYYMMDDHHMMSS+HHMM. Note the latter HHMM is timezone offset from UTC which for time stamps in IST will be 0530. Thus, the total time stamp is exactly 19 characters wide. An example is 20180224112759+0530

  • gstin - This is the gstin on whose behalf this transaction is done. In some cases (eg. search API) it may not be the gstin used in the transaction and thus may be substituted by a different GSTIN. For all practical purposes this is the GSTIN to which the transaction will get billed to when Vayana GSP prepares billing statements at the end of the month.

  • api_action - This is the api action used in various APIs as published by GSTN or NIC

Once you build an auth token as described above it has to be populated in the request headers under the key X-Asp-Auth-Token

Signing the auth token#

Use the private key from the keypair you generated (and whose public key you sent to Vayana) to sign the auth token.

Various sample codes for signing the auth token are provided at Sample code snippets for signing the auth token.

The signed auth token must be added to the request headers under the key X-Asp-Auth-Signature

Various validations performed on the auth token#

  • Vayana GSP will extract ClientID from auth string and identify the public key registered against it. The auth string should have been signed by its matching private key. This approach provides authentication as well as non-repudation of the requests.
  • The Timestamp should be in YYYYMMDDHHMMSS+hhmm format and should not be older or in the future by more than 5 minutes where YYYY = 4 digit year, MM = 2-digit month, DD = 2 digit day of month, HH = 2 digit hour, MM = 2 digit minute, SS = 2 digit second and ± direction of timezone shift from UTC hh= 2 digit hour offset for timezone and mm= 2 digit minute offset for timezone. For timestamps expressed in IST, the last 5 characters will always be “+0530”
  • Txn ID will be the same txn that needs to be sent to GSTN when such are a part of the call