> ## Documentation Index
> Fetch the complete documentation index at: https://developer.sandbox.co.in/llms.txt
> Use this file to discover all available pages before exploring further.
# e-Invoice Authentication
> e-Invoice Authentication API takes API credentials set on the e-Invoice portal (NIC) and gives the e-Invoice access token in response. If you have not created API credentials, follow the steps here to create them.
#### Request body schema
**Prerequisites:** You must have API credentials to hit E-Invoice APIs. If not, [create API credentials](/api-reference/gst/compliance/guides/e-invoice/authentication/create_api_credentials).
## OpenAPI
````yaml api-reference/gst/compliance/openapi.json POST /gst/compliance/e-invoice/tax-payer/authenticate
openapi: 3.0.1
info:
title: compliance
description: >-
**GST Compliance API** enables businesses to automate compliance
requirements like [Taxpayer
verification](https://developer.sandbox.co.in/reference/search-gstin-api),
[GSTR
Filing](https://developer.sandbox.co.in/reference/gst-taxpayer-authentication),
[Generating
E-Invoices](https://developer.sandbox.co.in/reference/e-invoice-authentication-api),
and [E-Way
Bills](https://developer.sandbox.co.in/reference/e-way-bill-authentication-api).We
provide these APIs from GSTN-authorised GST Suvidha Providers, handling the
encryption-decryption and signing so you don't have to handle the
complexities.
version: 1.0.0
servers:
- url: https://api.sandbox.co.in
- url: https://test-api.sandbox.co.in
security: []
tags:
- name: Public
- name: Taxpayer
- name: Taxpayer Auth
- name: Returns
- name: GSTR-1 Documents
- name: File GSTR-1
- name: GSTR-2A Documents
- name: GSTR-2B Document
- name: File GSTR-3B
- name: GSTR-4
- name: File GSTR-9
- name: Invoice Management System
- name: GSTR-1A Documents
- name: File GSTR-1A
- name: Ledgers
- name: e-Invoice
- name: Sales e-Invoices for return period
- name: Purchase e-Invoices for return period
- name: Front Office Notices
- name: Front Office
- name: AATO
- name: e-Invoice1
- name: Authentication
- name: e-Invoice12
- name: E-Way Bill
- name: E-Way Bill1
- name: Authentication1
- name: Consignor
- name: Consolidated E-Way Bill
- name: Multi-Vehicle Movement
- name: Consignee
- name: Transporter
- name: Consolidated E-Way Bill1
- name: Multi-vehicle Movement
- name: Common
paths:
/gst/compliance/e-invoice/tax-payer/authenticate:
post:
tags:
- e-Invoice1
- Authentication
summary: E-Invoice Authentication
operationId: eInvoiceAuthenticate
parameters:
- name: force
in: query
description: >-
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
required: true
schema:
type: string
example: 'true'
- name: authorization
in: header
description: JWT access token
required: true
example: ''
schema:
type: string
- name: x-source
in: header
description: >-
Specifies the source to access, either primary (NIC 1) or secondary
(NIC 2)
required: false
example: ''
schema:
type: string
enum:
- primary
- secondary
default: primary
example: primary
- name: x-api-key
in: header
description: API key for identification
required: true
example: ''
schema:
type: string
- name: x-api-version
in: header
description: API version
required: false
example: ''
schema:
type: string
default: 1.0.0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EInvoiceAuthenticateRequest'
examples:
200 Authenticated:
value:
username: ACME_IND_API_QCK
password: QnVzaW5lc3NfQVBJX1FDSw
gstin: 29AAACQ3770E000
summary: 200 Authenticated
1015 Invalid GSTIN for user:
value:
username: ACME_IND_API_QCK
password: 3NfQVBJX1FDSw
gstin: 29AAACQ370E000
summary: 1015 Invalid GSTIN for user
1019 Incorrect password:
value:
username: ACME_IND_API_QCK
password: qnvzaW5lc3NfQV
gstin: 29AAACQ3770E000
summary: 1019 Incorrect password
1017 Incorrect user id:
value:
username: ACME_IND_API_ID
password: QnVzaW5lc3NfQVBJX1FDSw
gstin: 29AAACQ3770E000
summary: 1017 Incorrect user id
GEN5008 GSTN Server Error:
value:
username: '{{irp_einv_username}}'
password: '{{irp_einv_password}}'
gstin: '{{irp_einv_gstin}}'
summary: GEN5008 GSTN Server Error
GEN5008 GSTN Server Error (Postman):
value:
username: API_Quicko_QIP
password: PASSWORKD
gstin: 24ABKCS2033B1ZV
summary: GEN5008 GSTN Server Error (Postman)
responses:
'200':
description: >-
1015 Invalid GSTIN for user / 200 Authenticated / 1019 Incorrect
password / 1017 Incorrect user id / GEN5008 GSTN Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/EInvoiceAuthenticateResponse'
examples:
200 Authenticated:
summary: 200 Authenticated
value:
code: 200
data:
ErrorDetails: null
InfoDtls: null
Status: 1
access_token: >-
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0YXhwYXllci1zZXNzaW9uIiwiZ3N0aW4iOiIyNEFCS0NTMjAzM0IxWlYiLCJpYXQiOjE3MTI5NDQxMDAsImV4cCI6MTcxMjk0NzcxMX0.sandbox-signature
expiry: 1708693832000
timestamp: 1763446641000
transaction_id: db0435d0-2a7d-42b2-9b44-94eef880bf60
1015 Invalid GSTIN for user:
summary: 1015 Invalid GSTIN for user
value:
code: 200
data:
Data: null
ErrorDetails:
- ErrorCode: '1015'
ErrorMessage: Invalid GSTIN for this user
InfoDtls: null
Status: 0
timestamp: 1763446641000
transaction_id: 474bfffc-7f59-4f01-b658-454f36028cd3
1019 Incorrect password:
summary: 1019 Incorrect password
value:
code: 200
data:
Data: null
ErrorDetails:
- ErrorCode: '1019'
ErrorMessage: Incorrect Password
InfoDtls: null
Status: 0
timestamp: 1763446641000
transaction_id: ee1c96f8-9c41-45cd-b28f-0d5ea95d07cb
1017 Incorrect user id:
summary: 1017 Incorrect user id
value:
code: 200
data:
Data: null
ErrorDetails:
- ErrorCode: '1017'
ErrorMessage: Incorrect user id/User does not exists
InfoDtls: null
Status: 0
timestamp: 1763446641000
transaction_id: 799054c8-45b3-4cb4-8461-defcd98d2891
GEN5008 GSTN Server Error:
summary: GEN5008 GSTN Server Error
value:
code: 200
data:
error:
error_cd: GEN5008
message: GSTN Server Error
status_cd: '0'
timestamp: 1735661058000
transaction_id: 14f91604-cf57-4336-8e4b-e758de6be3c4
headers: {}
deprecated: false
security: []
components:
schemas:
EInvoiceAuthenticateRequest:
required:
- password
- username
- gstin
type: object
properties:
password:
type: string
username:
type: string
gstin:
maxLength: 15
minLength: 15
pattern: ^([0-9]{2}[0-9A-Z]{13})$
type: string
EInvoiceAuthenticateResponse:
oneOf:
- $ref: '#/components/schemas/EInvoiceAuthenticateSuccessResponse'
- $ref: '#/components/schemas/EInvoiceBusinessErrorResponse'
- $ref: '#/components/schemas/EInvoicePlatformErrorResponse'
description: >-
Authentication success, NIC business error, or platform error. These
variants use HTTP 200.
EInvoiceAuthenticateSuccessResponse:
allOf:
- $ref: '#/components/schemas/EInvoiceResponseMetadata'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/EInvoiceAuthenticateSuccessPayload'
EInvoiceBusinessErrorResponse:
allOf:
- $ref: '#/components/schemas/EInvoiceResponseMetadata'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/EInvoiceBusinessErrorPayload'
EInvoicePlatformErrorResponse:
allOf:
- $ref: '#/components/schemas/EInvoiceResponseMetadata'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/EInvoicePlatformErrorPayload'
EInvoiceResponseMetadata:
type: object
description: Metadata returned with an e-Invoice API response.
required:
- code
- timestamp
- transaction_id
properties:
code:
type: integer
enum:
- 200
description: HTTP-compatible Sandbox response code.
timestamp:
type: integer
format: int64
description: Unix timestamp in milliseconds.
transaction_id:
type: string
description: Request transaction identifier.
EInvoiceAuthenticateSuccessPayload:
type: object
required:
- Status
- access_token
- expiry
properties:
ErrorDetails:
type: array
items:
$ref: '#/components/schemas/EInvoiceErrorDetail'
nullable: true
InfoDtls:
type: array
items:
$ref: '#/components/schemas/EInvoiceInfoDetail'
nullable: true
Status:
type: integer
enum:
- 1
access_token:
type: string
description: Access token for subsequent e-Invoice calls.
expiry:
type: integer
format: int64
description: Access-token expiry as a Unix timestamp in milliseconds.
EInvoiceBusinessErrorPayload:
type: object
required:
- Data
- ErrorDetails
- Status
properties:
Data:
type: object
nullable: true
description: Null for a NIC business-error response.
ErrorDetails:
type: array
minItems: 1
items:
$ref: '#/components/schemas/EInvoiceErrorDetail'
nullable: true
InfoDtls:
type: array
items:
$ref: '#/components/schemas/EInvoiceInfoDetail'
nullable: true
Status:
type: integer
enum:
- 0
description: NIC business-error status.
EInvoicePlatformErrorPayload:
type: object
required:
- error
- status_cd
properties:
error:
$ref: '#/components/schemas/EInvoicePlatformError'
status_cd:
type: string
enum:
- '0'
description: Platform failure status.
EInvoiceErrorDetail:
type: object
required:
- ErrorCode
- ErrorMessage
properties:
ErrorCode:
type: string
description: NIC error code.
ErrorMessage:
type: string
description: NIC error message.
EInvoiceInfoDetail:
type: object
required:
- InfCd
- Desc
properties:
InfCd:
type: string
description: NIC informational code.
Desc:
oneOf:
- type: string
- type: object
required:
- AckDt
- AckNo
- Irn
properties:
AckDt:
type: string
AckNo:
type: integer
format: int64
Irn:
type: string
minLength: 64
maxLength: 64
description: NIC informational message or duplicate-IRN acknowledgement details.
EInvoicePlatformError:
type: object
required:
- error_cd
- message
properties:
error_cd:
type: string
description: Platform error code.
message:
type: string
description: Platform error message.
````