GST API Authentication Explained — How Does It Actually Work?

If you have integrated standard REST APIs before, GST API authentication might seem like it has an extra step. Most APIs use a single API key or a standard OAuth bearer token. GST APIs in India use both and the reason matters forhow you implement it correctly.

The government’s GST infrastructure does not just need to know which application is making a request. It needs to know which registered taxpayer is authorising each compliance operation. Every IRN generated, every E-Way Bill created, every GSTIN validated these are recorded against a specific taxpayer in the government’s system. The authentication model reflects this compliance reality.

The Two-Layer Authentication Model

Layer one is the API Key. This is a permanent credential issued by PeriOne when you create a developer account. It identifies your application to the platform. It never expires unless you rotate it. It goes in the x-api-key header on every single request — including the authentication call itself.

Layer two is the Session Token. This identifies which GSTIN is performing the current operation. It expires after six hours. It goes in the Authorization header as a Bearer token on every API call except the authenticate endpoint.

You cannot skip either layer. A missing API key returns 403. A missing or expired session token returns 401.

The Authentication Endpoint — Full Request and Response

The authentication endpoint is:

    POST /authenticate

Send these headers:

    Content-Type: application/json

    x-api-key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

With this JSON body:

    {

      “gstin”: “29DDDDD3333D1Z8”,

      “app_key”: “your_client_secret_from_perione_console”

    }

A successful authentication returns:

    {

      “status”: “success”,

      “data”: {

        “auth_token”: “eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…”,

        “token_expiry”: “2024-11-15T20:00:00Z”,

        “gstin”: “29DDDDD3333D1Z8”,

        “issued_at”: “2024-11-15T14:00:00Z”

      }

    }

A failed authentication returns:

    {

      “status”: “error”,

      “error_code”: “AUTH002”,

      “message”: “Invalid GSTIN or app_key. Verify credentials in PeriOne console.”,

      “http_status”: 401

    }

The Four Headers Every GST API Call Requires

After successful authentication, every subsequent request whether for e-Invoice, E-Way Bill, or GSTIN validation must include these four headers:

    Content-Type:  application/json

    x-api-key:     pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

    Authorization: Bearer eyJhbGciOiJSUzI1NiI…

    gstin:         29DDDDD3333D1Z8

The x-api-key identifies your application. The Authorization token identifies the active GSTIN session. The gstin header tells the API which taxpayer’s compliance records this operation applies to. Missing any one of these returns a 401 Unauthorized response.

Authentication Error Codes

AUTH001 means your API key is invalid. Check the key in your PeriOne developer console and confirm you are not accidentally using a sandbox key against the production endpoint.

AUTH002 means your GSTIN or client secret is wrong. Verify both in your PeriOne

account settings.

AUTH003 is the most common production error — your session token has expired. This is entirely preventable with proactive token refresh. Check token expiry before every API call and refresh when within five minutes of expiry.

AUTH004 means the token was invalidated server-side. Clear your cached token immediately and re-authenticate. Do not retry with the same token.

AUTH005 means the GSTIN is not authorised for the specific API you are calling. Check that the API module is enabled in your PeriOne plan.

AUTH006 means your server’s IP address is not on the whitelist in PeriOne’s security settings. Add your server’s public IP there.

AUTH007 means you are calling the authenticate endpoint too frequently a clear sign that token caching is not implemented. Authenticate once per GSTIN session and reuse the token for all API calls within its six-hour window.

Token Caching and Refresh — The Correct Pattern

The wrong approach is authenticating before every API call. This is slow, wasteful, and triggers AUTH007. The right approach caches the token with its expiry timestamp and reuses it.

Before every API call, check whether the cached token is within five minutes of expiry. If yes, call authenticate, update the cache, and proceed. If no, use the cached token directly. The five-minute buffer accounts for network latency between when you check the token and when the server validates it.

Additionally, if you receive a 401 despite having a seemingly valid cached token, immediately clear the cache, call authenticate to get a fresh token, and retry the original request exactly once.

Multi-GSTIN Authentication

Enterprises with multiple GSTINs must maintain separate session tokens per GSTIN. A token issued for one GSTIN cannot be used for operations on a different GSTIN. The correct pattern is a token cache keyed by GSTIN a map or dictionary where each GSTIN stores its own token and expiry value.

When an API call is made for a specific GSTIN, look up that GSTIN in the cache. If the token is valid, use it. If expired or absent, authenticate for that GSTIN specifically, update its cache entry, and proceed.

The Complete Authentication Flow

  PeriOne Developer Console

            |

            | Generates: API Key (permanent) + Client Secret

            |

    Your application (on first API call)

            |

            |— POST /authenticate

            |    Body: { gstin, app_key }

            |    Header: x-api-key

            |            |

            |    Returns: { auth_token, token_expiry }

            |    Cache: { gstin –> (token, expiry) }

            |

    Every Subsequent API Call

            |

            |— Check: Is cached token valid?

            |    YES –> Use cached token

            |    NO  –> Re-authenticate –> Update cache

            |

            |— Build request with headers:

            |    x-api-key: permanent key

            |    Authorization: Bearer session token

            |    gstin: the operating GSTIN

            |

            |— On 401 Response:

                 Invalidate cache –> Re-authenticate –> Retry once

Security Practices That Are Not Optional

Never hardcode API keys or client secrets in source code files. Use environment variables in development and a secrets manager in production. Anyone with access to your source code would otherwise be able to generate real compliance transactions on your behalf.

Never commit .env files to version control. Add. env to your. gitignore before the first commit.

Whitelist your server’s public IP in PeriOne’s security settings. Even if credentials are accidentally exposed, an attacker from a non-whitelisted IP cannot use them.

Rotate API keys when team members with access leave and at least once annually.

GST API authentication is a two-layer system — a permanent API key identifying your application and a short-lived session token identifying the GSTIN performing each operation. Build a token manager that handles caching, proactive refresh, and 401 retry as a single reusable component. Once built correctly, authentication becomes invisible to the rest of your integration code.