Skip to main content
1

Authenticate

To begin the GST Taxpayer workflow, your application must first authenticate using the Authenticate endpoint to obtain the Sandbox JWT access token.This endpoint requires your API Key and API Secret, and returns a JWT access token that’s valid for 24 hours. This token is required for all subsequent API calls.

cURL Request

curl --request POST \
  --url https://api.sandbox.co.in/authenticate \
  --header 'accept: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxxxxxxx' \
  --header 'x-api-secret: xxxxxxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
When authentication is successful, you’ll receive the Sandbox JWT access token in the response. This token must be used in the authorization header (without the Bearer prefix) for all subsequent API calls.
2

Request OTP

Once you have the Sandbox JWT access token, request an OTP using the Generate OTP endpoint.You need to provide the taxpayer’s username (typically their registered email) and GSTIN (15-character GST Identification Number).

cURL Request

curl --request POST \
  --url https://api.sandbox.co.in/gst/compliance/tax-payer/otp \
  --header 'accept: application/json' \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'x-source: primary' \
  --data '{
  "username": "acme.com",
  "gstin": "29AAACQ3770E000"
}'
This will send an OTP to the taxpayer’s registered mobile number or email address, depending on the configuration.
3

Verify OTP

After receiving the OTP, verify it using the Verify OTP endpoint.Include the OTP as a query parameter and provide the same username and GSTIN in the request body. Upon successful verification, this will initiate a taxpayer session and return a Taxpayer access token that’s valid for 6 hours.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/otp/verify?otp=575757' \
  --header 'accept: application/json' \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'x-source: primary' \
  --data '{
  "username": "acme.com",
  "gstin": "29AAACQ3770E000"
}'
The response will include a Taxpayer access token which you’ll use for GST taxpayer-specific API calls, along with the session expiry timestamp (session_expiry and token_expiry). The token is valid for 6 hours from the time of generation.
Token Validity: The Taxpayer access token is valid for 6 hours. You can check the token_expiry timestamp in the response to know when the token will expire. If your workflow exceeds 6 hours, use the refresh session endpoint before expiry.
4

Refresh Taxpayer Session

Once you have a Taxpayer access token, you can extend the session without user intervention using the Refresh Session endpoint.This endpoint allows you to refresh the taxpayer session and extend access for another 6 hours, enabling seamless automation without requiring the user to authenticate again. You can refresh the token multiple times until the maximum session duration set on the GST Portal is reached.
Important: After the maximum session duration set on the GST Portal has passed, or if the token is not refreshed before expiry, you’ll need to complete the OTP verification process again to get a new authenticated session.

cURL Request

curl --request POST \
  --url https://api.sandbox.co.in/gst/compliance/tax-payer/session/refresh \
  --header 'accept: application/json' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
The refreshed token can be used to make GST taxpayer API calls such as filing GSTR returns, accessing ledgers, and managing invoices.