Skip to content
Star GameStar Game Docs

Exchange a one-time launch code for a player and an operator session

POST
/players/authenticate
curl --request POST \
  --url https://operator.example.com/game-wallet/v1/players/authenticate \
  --header 'Content-Type: application/json' \
  --header 'webhook-signature: <webhook-signature>' \
  --data '{ "launch_code": "example", "game_id": "lantern", "client_ip": "example" }'

The host app hands the game page an opaque, short-lived launch_code that SHOULD be single-use. The platform exchanges it here once and never stores it. Operators whose launch code is a reusable app token (so a page reload keeps working) remain conformant; the conformance suite reports single-use as advisory. session_id is echoed back on every debit so the operator can refuse new bets after logout, ban or limit breach.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
launch_code
required
string
<= 4096 characters
game_id
required
string

Example 

lantern
client_ip

Player IP as seen by the platform (may be empty)

string

Responses

Section titled “Responses”

200

Section titled “200”

Player identity

Media typeapplication/json
object
player_id
required

Stable operator player id

string
<= 64 characters
session_id
required

Operator session; echoed on debits

string
<= 256 characters
display_name
string
avatar_url
string format: uri
currency
required
string
balance
required

Integer amount in minor units, as a decimal string.

string
/^-?[0-9]{1,19}$/
language

BCP 47 tag, e.g. en, ar, zh-Hant

string
country

ISO 3166-1 alpha-2

string

Example 

{
  "currency": "GOLD",
  "balance": "1500"
}

401

Section titled “401”

invalid_launch_code (unknown, used or expired) or invalid_signature

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
Allowed values: invalid_signature invalid_launch_code malformed_request player_not_found transaction_not_found rate_limited unavailable internal not_found
detail
string

Example 

{
  "type": "https://game-platform.dev/problems/rate_limited",
  "code": "invalid_signature"
}

default

Section titled “default”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
Allowed values: invalid_signature invalid_launch_code malformed_request player_not_found transaction_not_found rate_limited unavailable internal not_found
detail
string

Example 

{
  "type": "https://game-platform.dev/problems/rate_limited",
  "code": "invalid_signature"
}