Skip to content
Fixedmark

Payments and India APIs · 11 min read

Updated

GST E-Invoice API IP Whitelisting, Direct vs GSP

To call the GST e-invoice API directly, you submit up to 4 Indian static IP addresses for whitelisting (3 for the e-way bill API), along with a sandbox test report, and every production call must leave from one of them. If you go through a GSP instead, NIC whitelists the GSP's servers and you whitelist nothing at the IRP.

On this page

Who calls the IRP API directly

E-invoicing has applied to businesses with aggregate turnover above ₹5 crore since 1 August 2023, under Notification 10/2023-Central Tax. Each invoice, debit note, and credit note for B2B and export supplies goes to an Invoice Registration Portal (IRP), which returns an IRN, a signed invoice, and a QR code. Many businesses never call the API themselves. They use an ERP plugin or a GST Suvidha Provider (GSP).

NIC's e-invoice process note lists the ways to generate an IRN. Only some of them make your own IP address matter.

IRN generation modes on the NIC IRP, and whose IP is whitelisted
ModeWho calls the IRPYour IP whitelisted at NIC
Offline tool (bulk upload)You, through the web portalNo
Through a GSPThe GSP's serversNo
Through a registered ERPThe ERP providerNo
Direct integrationYour own systemYes, up to 4 IPs
Through a sister concern (same PAN)Your system, with the sister concern's client IDYes, the same IP as the sister concern
Existing e-way bill API accessYour systemYes, the IPs already whitelisted for e-way bill

Direct access is not open to everyone on every IRP. NIC's API on-boarding page says that taxpayers with annual turnover of ₹100 crore and above in the previous financial year may get API access. GSTN's comparison of all six IRPs, dated 14 November 2023, says NIC1, NIC2, and Cygnet show the Direct API option only at ₹100 crore or more. IRIS IRP is open to direct integration for all B2B and SEZ taxpayers with e-invoicing enabled, and Clear IRP says all taxpayers eligible for e-invoicing can use its APIs. So a ₹20 crore business that wants its own integration can go to IRIS or Clear IRP, or use a GSP.

What the IP whitelisting step asks for

Each IRP runs its own whitelist, and each publishes its own rules. The details are close, but they are not identical.

Static IP rules for direct API access, as each portal publishes them
PortalIP ruleOther conditions
NIC e-invoice (einvoice1)Up to 4 Indian static IPsTLS 1.2 or later, a sandbox test summary report, a project manager and a technical SPOC
IRIS IRP (einvoice6)Indian IPs only, at least 1 and at most 4GST registration certificate as KYC, primary SPOC, a test report
NIC e-way billUp to 3 Indian static IPsAround 10,000 transactions a month per GSTIN, an SSL or TLS domain, a pre-production system

Sources for each row are NIC's on-boarding page, IRIS IRP's production access guide, and the e-way bill API pre-requisites. Four points on the NIC page matter most for planning.

  • Verification of the report and whitelisting of the IPs can take 4 to 5 days, so NIC asks you to submit well before go-live.
  • NIC asks you to verify the addresses before you submit them, because a whitelisted IP takes more time to change.
  • NIC recommends backup connectivity from a different service provider at your location.
  • Access starts over the internet. The page says users would later move to MPLS links provisioned by GSTN, with a cut-off date to be announced. We found no published cut-off date as of November 2026.

The addresses must be Indian. A server in Singapore or Virginia does not qualify, even if it is a dedicated static IP. NIC does not publish how it decides that an address is Indian, so pick addresses hosted in an Indian region and confirm the country with a geolocation lookup before you submit.

The e-invoice and e-way bill systems share IPs. NIC's process note says that if you already have e-way bill API access, you use the same credentials and the e-way bill whitelisted IPs for e-invoice. A release note reproduced by StudyCafe says you do not need to request separate whitelisting for the e-Invoice2 API. Group companies under one PAN can share one client ID, but NIC says the public IP used by your company and the sister concern must be the same when calling the production APIs. That rule is a good reason to run one central egress point for the whole group.

The direct onboarding sequence on NIC

The order matters, because the IPs you submit are tied to the test report and to the client credentials that follow.

  1. 1
    Register on the sandboxRegister your GSTIN on the NIC sandbox and build against it. NIC wants testing done through your own ERP or accounting application, not its online testing tool.
  2. 2
    Fill in the test summary reportRun every API you will use, with success and failure cases, and record the results in NIC's test summary format. Taxpayers upload the report as a PDF on the production portal.
  3. 3
    Decide your egress IPsFix the addresses before you apply. Count the IPs your production traffic can leave from today and after a failover, and keep the total at 4 or fewer.
  4. 4
    Submit IP whitelistingOn einvoice1.gst.gov.in, open API Registration, then IP Whitelisting. Enter the production IPs and submit. NIC's network team reviews and whitelists them.
  5. 5
    Create the API userChoose Create API User and set a username and password. Registration gives you a client ID and client secret. Other GSTINs under the same PAN reuse the client ID but each needs its own API user.
  6. 6
    Call production from the whitelisted IPs onlyPoint your client at the production API details NIC gives you, and make sure every call leaves from a submitted address.
Menu names and thresholds change. Check the current on-boarding page of the IRP you use before you apply. This post is not tax or legal advice.

Direct integration or a GSP

Going through a GSP moves the whitelist problem off your plate. NIC whitelists the GSP's servers once, and your app calls the GSP's API with the GSP's own authentication. You create an API user on the IRP portal, select the GSP, and hand those credentials to the GSP.

The direction of allowlisting can flip. ClearTax's GSP API reference lists the IPs of its own sandbox and production endpoints under URLs to be used or whitelisted. Those are for your outbound firewall, if you run one, not a list of your IPs that the GSP checks. Whether a given GSP also restricts your calls by IP is that provider's policy. Ask during onboarding.

Direct IRP access compared with a GSP
QuestionDirectThrough a GSP
EligibilityDepends on the IRP; ₹100 crore on NICAny e-invoicing taxpayer
Your IPs whitelisted at the IRPYes, up to 4 Indian static IPsNo
Who handles payload encryptionYouThe GSP
Ongoing costYour engineering time and a fixed egress IPThe GSP's fees
Data pathYour system to the IRPYour system to the GSP to the IRP

Direct access suits teams that generate IRNs at volume, want no third party in the data path, or already run an e-way bill API integration. A GSP suits teams that want the quickest route, or whose turnover rules out the Direct API option on NIC.

Why the egress IP is the fragile part

Credentials and code rarely change after go-live. The source IP is what breaks later, often after an infrastructure change nobody linked to GST.

  • Serverless and PaaS platforms send outbound traffic from shared addresses that change. A move to Vercel, Lambda, Cloud Run, or Railway quietly changes the IP the IRP sees. Why serverless egress IPs change covers each platform.
  • A NAT gateway or elastic IP gets replaced during a VPC rebuild or a move to another region.
  • A second office or a DR site starts making calls from its own ISP address.
  • A sister concern moves to a new host, and the shared-IP rule breaks for both companies.
  • You submitted IPv4 addresses and the client starts preferring IPv6, so the IRP sees an address that is not on the list. Check what your platform does with IPv6 egress and IPv4-only allowlists.

Debugging is harder than it should be. NIC's published vital error codes include 1010 for an invalid client ID or secret and 1018 when the client ID is not mapped to the user, but none of the published codes names a non-whitelisted IP. If production calls time out or the connection fails while the sandbox works, check the source IP first.

An outage here has a deadline attached. GSTN's advisory of 5 November 2024 says that from 1 April 2025, taxpayers with AATO of ₹10 crore and above cannot report e-invoices older than 30 days. A whitelist change takes days, so a broken egress IP can push invoices toward that limit.

Ways to keep one fixed egress IP

You need between one and four Indian IP addresses that stay put for years. There are three common ways to get them.

Fixed Indian egress options for IRP calls
OptionHow it worksWatch out for
Office or data center static IPAn ISP leased line or business plan with a static IP, and the integration runs on premisesOne ISP is one point of failure; NIC itself recommends backup connectivity
Cloud VM or NAT gateway in an Indian regionAn elastic or reserved IP on a VM or NAT gateway in an Indian region such as MumbaiOnly works for workloads inside that VPC; NAT gateway hourly and per-GB charges
Static IP egress proxyYour app sends only IRP calls through an HTTPS or SOCKS5 proxy with a dedicated Indian IP pairThe proxy must be dedicated to you and hosted in India

Whatever you choose, plan for failure inside the 4-address budget. Two addresses on separate hosts give you failover and leave room for two more, such as an office line for manual testing. Static IP pairs and failover explains why one address is a single point of failure. If you are weighing a NAT gateway, read NAT gateway hidden costs or try the NAT gateway cost calculator first.

Never submit an address that other customers share. If another tenant can send traffic from your whitelisted IP, the whitelist protects nothing, and their bad traffic can be attributed to you. NIC reserves the right to block or suspend taxpayers when it detects malicious traffic. Cloud IP ranges are not an allowlist goes into the shared-address problem.

Route only IRP calls through the fixed IP

The IRP is usually one of many outbound destinations in your app. Configure the proxy on the client that talks to the IRP, and leave other traffic direct. This keeps proxy bandwidth small and makes the egress path for GST calls explicit in code. Selective proxying with per-client agents covers why environment variables like HTTPS_PROXY are a riskier choice.

The example below is the NIC authentication call from the v1.04 auth spec, following the encryption steps in NIC's Java sample. The credentials JSON is Base64-encoded, then encrypted with the IRP public key using RSA PKCS#1 v1.5. The response carries a session key (SEK) encrypted with your AppKey using AES in ECB mode. Only this client uses the proxy.

irp_auth.py
# pip install requests cryptography
import base64
import json
import os
import secrets

import requests
from cryptography.hazmat.primitives import padding as sym_padding
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

# Only IRP calls use the fixed-IP proxy. Everything else goes direct.
PROXY = os.environ["IRP_PROXY_URL"]
PROXIES = {"http": PROXY, "https": PROXY}

# The auth URL from the production API details NIC sends you.
AUTH_URL = os.environ["IRP_AUTH_URL"]


def authenticate() -> tuple[str, bytes]:
    with open(os.environ["IRP_PUBLIC_KEY_PEM"], "rb") as f:
        public_key = serialization.load_pem_public_key(f.read())

    app_key = secrets.token_bytes(32)  # 44 chars once Base64-encoded
    # Compact JSON: RSA-2048 with PKCS#1 v1.5 encrypts at most 245 bytes.
    creds = json.dumps({
        "UserName": os.environ["IRP_USERNAME"],
        "Password": os.environ["IRP_PASSWORD"],
        "AppKey": base64.b64encode(app_key).decode(),
        "ForceRefreshAccessToken": False,
    }, separators=(",", ":"))
    encrypted = public_key.encrypt(
        base64.b64encode(creds.encode()), padding.PKCS1v15()
    )

    res = requests.post(
        AUTH_URL,
        json={"Data": base64.b64encode(encrypted).decode()},
        headers={
            "client_id": os.environ["IRP_CLIENT_ID"],
            "client_secret": os.environ["IRP_CLIENT_SECRET"],
            "Gstin": os.environ["IRP_GSTIN"],
        },
        proxies=PROXIES,
        timeout=30,
    )
    res.raise_for_status()
    body = res.json()
    if str(body.get("Status")) != "1":
        raise RuntimeError(f"IRP auth failed: {body.get('ErrorDetails')}")

    # The SEK comes back AES-ECB encrypted with your AppKey.
    decryptor = Cipher(algorithms.AES(app_key), modes.ECB()).decryptor()
    padded = decryptor.update(base64.b64decode(body["Data"]["Sek"]))
    padded += decryptor.finalize()
    unpadder = sym_padding.PKCS7(128).unpadder()
    sek = unpadder.update(padded) + unpadder.finalize()
    return body["Data"]["AuthToken"], sek

The token lasts 360 minutes in production and 60 in the sandbox, and calling auth again inside that window returns the same token. Cache it per GSTIN instead of authenticating on every invoice. That also keeps you clear of NIC's error 3095, which temporarily disables a client that sends many erroneous requests.

Before you submit IPs, and again after every deploy, confirm which address your IRP client actually leaves from. Run the check through the same proxy URL your code uses.

Terminal
# Count which egress IPs 20 new connections leave from.
# Every address printed must be on your IRP whitelist.
for i in $(seq 1 20); do
  curl -s --proxy "$IRP_PROXY_URL" https://fixedmark.com/api/ip
done | sort | uniq -c

Doing this with Fixedmark

NIC accepts only Indian static IPs, so the region decides whether a Fixedmark pair qualifies. Of the planned launch regions (Mumbai, Singapore, Newark, and Ashburn), only Mumbai is in India. A pair in any other region does not meet that rule. Create the app in Mumbai on a plan with a dedicated pair, then submit both addresses on the IRP whitelist, which uses two of the four slots. NIC does not say how it checks that an address is Indian, so run a geolocation lookup on both addresses before you submit. Your code keeps running on Vercel, Railway, Lambda, or anything else, and only the IRP client uses the proxy URL. The bank and UPI API use case walks through the same setup for banks.

  • Use a dedicated pair. The 7-day trial and the Starter plan run on a shared IP pair, so do not submit those addresses to an IRP. A dedicated pair comes with Pro, planned at $29 a month.
  • TLS runs end to end from your code to the IRP, and Fixedmark does not decrypt it. The IRP payloads are also encrypted at the application layer with the SEK, so request contents are never visible to the proxy. See security.
  • Connection logs show the destination, egress IP, and result of each connection, which helps when a production call fails and the sandbox works. See connection logs.
  • On Business and up, a destination allowlist can restrict the proxy credential to the IRP host on port 443, so a leaked token reaches nothing else.

Fixedmark is in early access and not generally available, and prices are planned launch prices. Language setup guides for the proxy URL are in the Python, Node.js, and Java docs, and verify your egress IP covers the checks above in more depth.

Sources

Checked November 2026. Confirm current details on the vendor's site before you decide. Prices and limits change.

Blog

Frequently asked questions

Do I need IP whitelisting if I use a GSP for e-invoicing?

Not at the IRP. NIC whitelists the GSP's servers, and you only create an API user on the e-invoice portal and select the GSP. Some GSPs publish their own endpoint IPs for your outbound firewall, and a GSP may have its own access rules, so check its onboarding guide.

How many IPs can I whitelist for the e-invoice API?

NIC allows up to 4 Indian static IPs for production access. IRIS IRP asks for at least 1 and at most 4, Indian only. The e-way bill API allows up to 3.

Can I use the same IPs for e-way bill and e-invoice?

Yes. NIC says taxpayers who already have e-way bill API access use the same credentials and the e-way bill whitelisted IPs for the e-invoice system.

Can I whitelist a server in Singapore or the US?

No. NIC and IRIS IRP both ask for Indian static IPs. Run the integration from an Indian region, an Indian office line, or a proxy with a dedicated Indian IP.

How long does IRP IP whitelisting take?

NIC's on-boarding page says verification of the test report and whitelisting of the IPs may take 4 to 5 days, and that changing a whitelisted IP later takes more time. Submit well before go-live.

Make it fixed.

Fixedmark is in early access. Join the list to get dedicated static IPs when your region opens.