Overview

To access the API, application should first authenticate using the credentials. The credentials have to be generated by the taxpayers and get the auth token issued. Same auth token is to be used to access subsequent APIs. Validity of the auth token will be 360 minutes (60 minutes on Sandbox for ease of testing). Any hits to this API within these 360 minutes will return the same token, hence there is no need to hit the API unless the token has expired. However, there is a provision to forcefully generate a new token within the last 10 minutes of expiry by calling this API with "ForceRefreshAccessToken" set to "True". On expiry, same authentication API needs to be invoked to issue new auth Token.

Sequence Diagram

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

URL <URL>/v1.04/auth

Content-Type

application/json

Method

POST

Request Header


Attributes
Description

client_id

client id to be provided by E-Invoice System

client_secret

client secret to be provided by E-Invoice System

Gstin

GSTIN of the authenticated user

Request Payload

Data Json containing the Credentials is encoded using Base64 and then encrypted using e-Invoice public Key
Attributes Description
UserName Username of Tax payer as created on E-Invoice portal for API Integration
Password Password of Tax payer as in E-Invoice portal for API Integration
AppKey Any 32 character random unique id generated by user, identifying unique user session. App_key will be generated and converted to base 64 string.
ForceRefreshAccessToken The value of this attribute to be set true, if client needs to refresh the token 10 minutes before expiry

Response Payload

Attributes Description
Status Status of the authentication request(values 1-Success and 0- Failure)
Data If Status is ‘1’
ClientId Client Id
UserName User Name
AuthToken Authorization token
Sek Session Encryption Key generated using AES 256(AES/ECB/PKCS7Padding) algorithm. Encrypted () with AppKey
TokenExpiry Token Expiry time. Date format is ‘yyyy-MM-dd HH:mm:ss ’
ErrorDetails If Status is ‘0’
ErrorCode Unique error code
ErrorMessage Error Description
InfoDtls Any additional message to be conveyed would be passed.

Sample JSON (Request)

Authentication Request

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

JSON corresponds to the "Data" element of Authentication Request above

 {
    "UserName":"testuser",
    "Password":" < Password in plain text >",
    "AppKey":" < Randomly generated key>",
    "ForceRefreshAccessToken": true
 }              
               

Sample JSON (Response)

Authentication Response (Success)

{
"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 > "
}

JSON(in case of error)


"status": "0",
"Data": null,
"ErrorDetails":"<Errors JSON>",
"InfoDtls": "<alert message >"
}

Frequently Asked Questions

1. Getting error 'Invalid Auth Token' while generating an e-Invoice through API and it is getting expired within 6 Hours.
A. Auth Token will be active for 6 hours since the first successful login. Even if the the Auth API is called again before 6 hours, same token will be returned and the time is not reset. Hence you can generate new Auth token only when it expires after 6 hours. For example: If you have authenticated at 12:00, token will be active till 06:00 If auth API is called at 02:00, still the same token will be active till 06:00 and not till 08:00