Seamless Wallet/authenticate

Player authentication

Callback · Provider → Operator

POST{callback_url}/authenticate

When the player opens the launch_url, Boss Hub calls this endpoint so you can verify the player token you passed in the launch request. The game does not open until an OK reply arrives. If the game provider re-authenticates the player during the session, the same call arrives again.

Headers

Header	Description
Content-Type	application/json
X-Operator-Id	Your operator ID
X-Timestamp	Unix seconds. Reject it outside ±30 s
X-Signature	hex(HMAC_SHA256(secret, ts + "." + "POST" + "." + path + "." + body)). path is the full path of your callback address, base path included, e.g. /bossgaming/bet. See Signing
X-Request-Id	The ID of the request. This call is not retried
X-Api-Key	The API key whose secret signed the callback. Selects the right secret when you have several keys

Body parameters

tokenstringrequired

The player session token you passed in the launch request.

session_idstring

The game session opened by launch.

site_idstring

Site code, e.g. site_mrd01. Tells apart sites that share one callback address.

Two tokens: The token here is your own player session token. The single-use token inside launch_url belongs to Boss Hub and never reaches you.

Reply: player_id is required and must equal the player_id of the launch request; otherwise the game does not open and a security event is recorded. If you send currency, it must equal the session currency. balance is the balance the game shows at start; without it, 0 is shown.

Single attempt: This call is not retried. If no reply arrives within the wallet timeout (3 s by default), or the reply is not HTTP 200, the game does not open.

POST /bossgaming/authenticate HTTP/1.1
Content-Type: application/json
X-Operator-Id: op_meridyen
X-Timestamp: 1762344000
X-Signature: 3d71ac…09f2
X-Request-Id: req_01HF3K7N
X-Api-Key: pk_test_…

{
  "token": "tok_8f2a6c41",
  "session_id": "ses_01HF3K7M",
  "site_id": "site_mrd01"
}

200Successful response

{
  "status": "OK",
  "player_id": "u_88213",
  "currency": "USD",
  "balance": 150.60
}

200Business rule error (HTTP 200 + code)

{
  "status": "ERROR",
  "code": "INVALID_TOKEN"
}

Error codes

Code	Meaning	Boss Hub behaviour
INVALID_TOKEN	Token invalid or expired	The game does not open; the player’s browser gets 403 INVALID_TOKEN
PLAYER_BLOCKED	Player restricted / self-exclusion	The game does not open; the player’s browser gets 403 PLAYER_BLOCKED
INVALID_SIGNATURE	Signature could not be verified	The game does not open; the browser gets 403 INTERNAL_ERROR
INTERNAL_ERROR	Operator error	The game does not open; the browser gets 403 INTERNAL_ERROR
—	Timeout, a reply other than HTTP 200	The game does not open; the browser gets 503 PROVIDER_UNAVAILABLE
—	HTTP 200 but the JSON cannot be read (e.g. a WAF page)	The game does not open; the browser gets 500 INTERNAL_ERROR and the launch_url counts as used

Other answers the player can get when opening launch_url: Game launch.

← PreviousEnvironments & IP allowlist Next →balance