Skip to content

Understanding APIs#

Base URL#

https://{env}.enriched-api.vayana.com

where env is the environment,

  • solo is for sandbox
  • live is for production

Module URLs#

For rest of the APIs in the suite following pattern will be the baseurl

https://{env}.enriched-api.vayana.com/{module}/{sub-module}/{version}

where,

module should be one of the below options,

  • ‘basic’ is for basic api services
  • ‘enriched’ is for enriched api services

also sub-module should be one of the below options,

  • ‘gstn’ is for gstn api services
  • ‘ewb’ is for e-way bill api services
  • ‘einv’ is for e-invoicing api services

Example

so for sandbox environment, where module is basic and sub-module is gstn for version ‘v1.0’ of the API, the url would be -

https://solo.enriched-api.vayana.com/basic/gstn/v1.0

Headers#

X-FLYNN-N-ORG-ID#

Org ID issued by the “authentication” server (ie theodore) - during the time of “login”

  • contains - plain text string
  • is required when - making an authenticated call
  • this helps us identify the Organization who is calling the API

Check here for the step-by-step process to get a unique ID for your OrOrganization.

X-FLYNN-N-USER-TOKEN#

Token issued by the “authentication” server (ie theodore) - during the time of “login” or “refresh”

  • contains - plain text string (actually it would ‘base64 encoded string or issued token’)
  • is required when - making an authenticated call

X-FLYNN-N-*#

Any key with prefix X-FLYNN-N- is a plain text value. All the non-sensitive data in the header are sent using stated header-key pattern.

  • contains - plain text string (non-sensitive information)
  • is required for - specific APIs only, when sending non-sensitive information in the header

X-FLYNN-S-REK#

Additionally, if client wish sending any sensitive data in or as request body; or sending any sensitive information in the header, following header is required, REK aka ‘Request Encryption Key’ which is of length 32, 48 or 64 chars string. Client can create a new string for each request (recommended, more secure) or re-use the key to encrypt any secret data passed in the request.

REK itself is encrypted using the public key shared by the server. Share the REK with server in the request header as an encrypted base64 string. Server will decrypt this ‘REK’ and use it to decrypt the sensitive information shared in the request.

Download server’s public key here

X-FLYNN-S-*#

Any key with prefix X-FLYNN-S- is an encrypted base64 string, the secret value is AES encrypted. As described above, all sensitive information/data must be encrypted using “32, 48 or 64 char” request encryption key (REK). The cipher algorithm to use for encryption will be AES with ECB as the encryption mode & PKCS7 padding. The base64 string of the encrypted bytes are set in the header or request body.

Crypto transformation algorithm used for encryption/decryption - AES/ECB/PKCS7PADDING using plain-text REK.

  • contains - base64 encoded string of the encrypted bytes (sensitive information)
  • is required for - specific APIs only, when sending sensitive information in the header

To check how to configure secret headers, please check encryption support page.

Checkout pseudo code below to understand above mentioned process to encrypt REK and secret data 

## Generation of REK and encrypting sensitive information

rek = get_random_string(chars=32)
e_rek = ecb_encrypt_via_rsa_public_key(key=public_key, data=rek, padding='PKCS1Padding')
b64_e_rek = b64_encode(data=encrypted_rek)

secret_data = "i-H0ld-som3-$ece2ts-inFO"
e_secret_data = aes_ecb_encryption(key=rek, data=secret_data, padding='PKCS7PADDING')
b64_e_secret_data = b64_encode(encrypted_secret_data)

## setting of header values

"X-FLYNN-S-REK" = "<< b64_e_rek >>",
"X-FLYNN-S-DATA" = "<< b64_e_secret_data >>"