GST API OAuth 2.0 Authentication

OAuth 2.0 client-credentials grant for the WhiteBooks GST API. Token expiry 1 hour, refresh transparent, mTLS optional on Enterprise.

Get sandbox keys → View OpenAPI docs Talk to sales

What is the GST API OAuth 2.0 Authentication?

The WhiteBooks GST API uses OAuth 2.0 client-credentials grant (RFC 6749 Section 4.4). Pass client_id + client_secret to POST /oauth/token and receive a bearer access_token (validity: 1 hour) and a refresh_token (validity: 24 hours).

For higher-security environments, the API supports mTLS (mutual TLS) authentication on Enterprise tier — your X.509 client certificate is bound to your tenant and bearer tokens are issued only over the mTLS channel. IP allow-listing is also available on all tiers.

Quick spec

Code examples

curl Node.jsPythonJava 
curl -X POST 'https://apisandbox.whitebooks.in/gst/oauth/token' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ /* payload */ }'
Node.js 
const res = await fetch('https://apisandbox.whitebooks.in/gst/oauth/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});
const data = await res.json();
Python 
import requests

resp = requests.post(
    'https://apisandbox.whitebooks.in/gst/oauth/token',
    headers={'Authorization': f'Bearer {access_token}'},
    json=payload,
)
data = resp.json()
Java 
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://apisandbox.whitebooks.in/gst/oauth/token"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .post(BodyPublishers.ofString(payload))
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(req, BodyHandlers.ofString());

Integrate in 3 steps

  1. Sign up at accounts.whitebooks.in — sandbox credentials issued instantly, no sales gate.
  2. Make your first call against the sandbox base URL using the code example above. Validate against your local model.
  3. Move to production once your tests pass — switch host to https://api.whitebooks.in/gst. Same payload, same response shape.

Frequently asked questions

What's the token expiry?

Access token: 1 hour. Refresh token: 24 hours. Refresh before expiry to maintain a continuous session.

Can I rotate client_secret?

Yes — generate a new secret in the dashboard. Old secret remains valid for 24h to enable zero-downtime rotation.

Is mTLS available?

Yes on Enterprise tier. Mount your client certificate; we bind to your tenant ID. Bearer tokens are then only issued over the mTLS channel.

How do I rotate certificates?

Upload new cert via dashboard with effective_from timestamp. We honor both old + new during the overlap window.

Explore the full GST API

This is one endpoint inside the WhiteBooks GST API suite. See the full documentation — every endpoint, every parameter, every error code.

Open the GST API page →

Related GST API endpoints

GSTR-1 Filing API → GSTR-2B Fetch API → GSTR-3B Filing API → GSTR-9 Annual Return API →
Schedule Demo