Overview

To access the API, application should first authenticate using the credentials shared and get the access token issued. Same access token to be used to access subsequent APIs. Access token will be configured to expire after 360 minutes. On expiry, same authentication API needs to be invoked to get new Access Token issued. The API header information is used for authentication and authorization purpose.

Sequence Diagram

The format and details of a sample API request is depicted in following table.

URL <URL>/authenticate/

Content-Type

application/json

Method

POST

Request Header


Attributes
Description

client-id

Client_id to be provided by E-WAY BILL SYSTEM

client-secret

Secret to be provided by E-WAY BILL SYSTEM

Gstin

GSTIN of the requesting Tax Payer

Request Payload

Attributes Description Value
action ACCESSTOKEN
username Username of Tax payer as created on Ewaybill portal for API Integration (Tax payer will use the option Mainmenu->Registration->GSP to register under GSP OR Tax payer will use the option Mainmenu->Registration->API to register directly for API Interface)
password Password of Tax payer as in Ewaybill portal for API Integration Encrypt(password, Ewaybill Public Key)
app_key Any 32 character random unique id generated by user identifying unique user session. App_key will be encrypted using Public key of E-WAY BILL using RSA algorithm.

Response Payload

Attributes Description Values
status Status of Authentication request 0 – for Failure; 1 – for Success
authtoken Authorization token is a universally unique identifier (UUID). Eg: 30431124-5cbd-4045-9840-4ebb18d70265",
sek Session Encryption key (SEK) is a 32 bit random secure key generated using AES 256 algorithm in the EWB system .App_key will be used as key to encrypt the Session Encryption key (SEK) using AES 256 (AES/ECB/PKCS7Padding) algorithm Eg:"IaxLuJcsqILZuYQX828I TxXlrRUM1ebdEIaqEXnlaK +xK/U7ZuM5xAayg7RB7mWp

Sample JSON (Request)

Authentication Request

{
"action":"ACCESSTOKEN",
"username":"nictexxst",
"password":"rjPf8Rr4Gjh9qvSDfoqOqyHPW+==",
"app_key":"e1d65bgSeTrTatc7atLhKWyUbM/ekfbAWu2dFMfyNuYS+ =="
}

Sample JSON (Response)

Authentication Response

{
"status":"1",
"authtoken":"a30WKqvWdLMkPH6M5V9X4AY",
"sek":"crdHoP73uRaLwSsg4o8RZCHgVrfydvF2K5IW3+kc/rI5SqOVJ52Thf1yCI4j"
}