e-Invoice Authentication

API to generate JWT access token required to call e-Invoice APIs

Overview

Users have to authenticate themselves using their e-Invoice portal credentials to call the e-Invoice APIs

Endpoint

HTTP Method	Resource
`POST`	/irp/tax-payer/authenticate?force={force}&gstin={gstin}

Request

Follow the below guidelines to call the API.

📘
The x-source provided by the user will be utilized for all the other e-Invoice API requests.

x-source description

The image below demonstrates how Sandbox employs various sources to communicate with the GST e-Invoice Server. To access the Sandbox e-Invoice Authentication API, users must specify a particular source via the x-source header attribute. Doing so will create an authorization token that is necessary for accessing other e-Invoice APIs. This authorization token includes both the selected source and the user's GSTIN. Therefore, any other e-Invoice APIs accessed using this authorization token will be directed through the chosen source for that authenticated GSTIN.

Note: The name of the sources is not subject to their performance/availability.

Headers

Param	Type	Description	Example
x-api-key	`string`	An API key is a public key to identify users when calling any Sandbox API.	key_live_ZUQT5UEf4......
x-source	`string`	Look here Possible Values - `primary`, `secondary` or `tertiary`	primary
Authorization	`string`	JWT Authorization token	eyJhsebihGyUf......

🚧
Currently, only primary source is live meaning secondary and tertiary will not work.

Query Parameters

Param	Type	Description	Example
force	`boolean`	The value of this attribute is to be set true if the client needs to refresh the token 10 minutes before expiry. Possible Values - `true` or `false`	false
gstin	`string`	15-character alpha-numeric unique identifier assigned to business entities registering under the GST regime.	22AAAAA0000A1Z5

Body

Param	Type	Description	Example
username	`string`	Username of Tax payer as created on E-Invoice portal for API Integration	testuser
password	`string`	Password of Tax payer as in E-Invoice portal for API Integration	Password in plain text

Sample CURL Request

curl --request POST \
     --url 'https://api.sandbox.co.in/irp/tax-payer/authenticate?force=true&gstin=22AAAAA0000A1Z5' \
     --header 'Authorization: xxxxxxxxxx' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: xxxxxxxxxx' \
     --header 'x-api-version: 1.0' \
     --header 'x-source: primary' \
     --data '
{
  "username": "testuser",
  "password": "<Password in plain text >"
}
'

❗️
Test Environment Not Available

Response

Param	Type	Description	Example
Status	`num`	Status of the authentication request. Possible values - `1` - Success `0` - Failure	1
access_token	`string`	Authorization token. Users will have to use this token for accessing other e-Invoice APIs. Note: This token is only valid for e-Invoice APIs.	eyJhbGciOiJIUzJhdWQ..........
ErrorDetails	`string`	If the Staus is 0, user will receive an array of objects containing `ErrorCode` and`ErrorMessage`	"ErrorCode": "1017", "ErrorMessage": "Incorrect user id/User does not exists"
InfoDtls	`string`	Any additional message to be conveyed would be passed.	null

Response Caching

Response caching is not available for this API. Learn more about our response caching mechanism here

Wallet Charges

Since E-Invoice Authentication API is a Paid API, a wallet charge of INR 0.25 + GST will take place.

Versioning

This API is currently in major version 1.0. Refer to our versioning policies here

Updated about 1 month ago