POST/NorenWClientAPI/ValidateHsToken

Validate HS Token

Server-to-server check that confirms a LoginId/token pair issued at login is still valid — used to gate access before handing a user off to an external integration such as Back Office.

API Endpoint

Method	`POST`
URL	`https://api.shoonya.com/NorenWClientAPI/ValidateHsToken`
Content-Type	`application/x-www-form-urlencoded`
Payload	`LoginId=<sLoginId>&token=<token>` — plain form fields, not a `jData`/`jKey` envelope.

Overview

Validate HS Token lets a third-party server confirm that a LoginId and token pair, handed to it by the trading site on redirect, is genuine and still active — before it grants that user access on its own end. This is the check step in an external integration flow: trading site → redirect with credentials → third party validates server-side → third party grants access.

Server-to-server onlyCall this from your backend, never from a browser or a client-side APK. The token is a live session credential — sending this request from the client would expose it in the same request meant to validate it.

Parameters

Field	Type	Required	Description	Allowed Values
LoginId	string	Required	The `sLoginId` value received from the Initiator site at login.	Account-specific
token	string	Required	The key obtained on successful login, passed along with `LoginId` to the third-party URL.	Session-specific

Request Examples

import requests

payload = {
    "LoginId": "FA12345",
    "token": "6f1a2c9e-8b3d-4a11-9e77-example-token",
}

response = requests.post(
    "https://api.shoonya.com/NorenWClientAPI/ValidateHsToken",
    data=payload,
)

# response body is plain text — "TRUE" or "FALSE", not JSON
is_valid = response.text.strip() == "TRUE"
print("Token valid:", is_valid)

const payload = new URLSearchParams({
  LoginId: "FA12345",
  token: "6f1a2c9e-8b3d-4a11-9e77-example-token",
});

try {
  const res = await fetch("https://api.shoonya.com/NorenWClientAPI/ValidateHsToken", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: payload,
  });

  // plain text response — "TRUE" or "FALSE"
  const text = await res.text();
  const isValid = text.trim() === "TRUE";
  console.log("Token valid:", isValid);
} catch (err) {
  console.error("Network/timeout error validating token:", err);
}

curl -X POST https://api.shoonya.com/NorenWClientAPI/ValidateHsToken \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "LoginId=FA12345" \
  --data-urlencode "token=6f1a2c9e-8b3d-4a11-9e77-example-token"

Response

text

// Valid — HTTP 200
TRUE

// Invalid LoginId or token — HTTP 200
FALSE

Plain text, not JSONThe response body is the literal string TRUE or FALSE — there is no stat/emsg envelope here, unlike most other endpoints. Compare the trimmed response body directly; don't attempt to JSON-parse it.

Value	Meaning
`TRUE`	Token is valid for the given LoginId.
`FALSE`	Invalid User Id or Token — treat identically to a failed auth check; don't try to distinguish the two causes from the response alone.

External Integration Flow

        User clicks link → Trading site passes UserId/Token/ClientId → Third-party server calls Validate HS Token → Trading site confirms TRUE/FALSE → Access granted or denied
      

Step	Detail
1. User action	User clicks a link on the trading site — e.g. "Back Office login".
2. Handoff	Trading site passes `User Id`, `Token`, and `Client ID` to the third-party URL, typically as query params on the redirect.
3. Server-side validation	The third party's own server — not its front end — calls Validate HS Token against the trading site's web server.
4. Access decision	If the trading site returns `TRUE`, the third-party application grants the user access; on `FALSE`, it denies it.

Best Practices

Always validate server-side on receipt of a redirect, even if the trading site's front end already appeared to authenticate the user — the client-side handoff isn't trustworthy on its own.
Compare the response body as trimmed plain text ("TRUE"/"FALSE"), not as JSON — this endpoint doesn't follow the stat/emsg convention used elsewhere in the API.
Treat FALSE as a hard deny. Don't retry automatically — an expired or invalid token needs the user to re-authenticate from the trading site, not a repeated validation call.
Don't cache a TRUE result past the immediate access decision — re-validate on each new redirect rather than trusting a previously-validated token indefinitely, since the underlying session can expire or be invalidated independently. See Token Renewal.
Confirm your server's egress IP is whitelisted before going live — see IP Whitelisting Guide.
If you're integrating as a registered vendor rather than a single account holder, coordinate this flow as part of onboarding — see For Vendors / Partners and Manual-Login-Oauth for the login handoff that precedes it.

Edit this page on GitHub

← Previous

Token Renewal

For Vendors / Partners