Authentication

WhiteBooks APIs use the OAuth 2.0 client_credentials grant. Exchange your client_id + client_secret for a bearer token valid for 1 hour. Include it in the Authorization header of every subsequent call. SDKs handle refresh transparently.

Get a token

POST https://api.whitebooks.in/oauth/token
Content-Type: application/json

{
  "grant_type":    "client_credentials",
  "client_id":     "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "scope":         "gst einvoice eway"
}

// Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type":   "Bearer",
  "expires_in":   3600,
  "scope":        "gst einvoice eway"
}

Use the token

GET https://api.whitebooks.in/gst/api/v1/gstin/29AAAAA0000A1Z5
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Refresh strategy

Tokens expire after 1 hour. SDKs cache and refresh transparently — you do not need to handle this manually. If you're using raw REST, request a new token whenever you receive 401 or your cached token's exp is within 5 minutes.

IP allow-listing (Enterprise)

Register a list of source IPs per client_id. Requests from any other IP are rejected with HTTP 403. Configure in the dashboard or via POST /accounts/api/v1/security/ip-allow-list.

SHA256-RSA request signing (Enterprise)

Optional secondary auth layer. The client signs each request body with its RSA private key using SHA-256; WhiteBooks verifies against your registered public key. Prevents request tampering even if a bearer token is leaked. Activate via dashboard.

Webhook signature verification

Outbound webhooks from WhiteBooks include X-WhiteBooks-Signature: t=<timestamp>,v1=<hmac-sha256>. Verify with your webhook secret. SDKs ship a helper: wb.webhooks.verify(body, signature, secret).

Related

Part of the WhiteBooks developer documentation cluster. See /llms.txt for the full machine-readable site index. Last updated 27 May 2026.