Contact UsSupportSignup

e-Invoice Authentication

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

Suggest Edits

Overview

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

Endpoint

HTTP MethodResource
POST/irp/tax-payer/authenticate?force={force}&gstin={gstin}

API Endpoint  Contact Us  Free Trial

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.

E-Invoice Source

Headers

ParamTypeDescriptionExample
x-api-keystringAn API key is a public key to identify users when calling any Sandbox API.key_live_ZUQT5UEf4......
x-sourcestringLook here
Possible Values -
primary, secondary or tertiary		primary
AuthorizationstringJWT Authorization tokeneyJhsebihGyUf......

🚧

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

Query Parameters

ParamTypeDescriptionExample
forcebooleanThe 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
gstinstring15-character alpha-numeric unique identifier assigned to business entities registering under the GST regime.22AAAAA0000A1Z5

Body

ParamTypeDescriptionExample
usernamestringUsername of Tax payer as created on E-Invoice portal for API Integrationtestuser
passwordstringPassword of Tax payer as in E-Invoice portal for API IntegrationPassword 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

ParamTypeDescriptionExample
StatusnumStatus of the authentication request.
Possible values -
1 - Success
0 - Failure		1
access_tokenstringAuthorization 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..........
ErrorDetailsstringIf the Staus is 0, user will receive an array of objects containing ErrorCode andErrorMessage"ErrorCode": "1017",
"ErrorMessage": "Incorrect user id/User does not exists"
InfoDtlsstringAny 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 2 months ago