Create a session

Real mode creates a game session whose 256-bit launch token is stored only as its SHA-256; demo mode creates no session and accepts no callbacks. A session expires 24 hours after its last callback, or after the client's shorter idle time.

POST/v1/sessions

Request

A client sends this request signed with its credential. The example is signed with the test API key test-key-test-key and the test secret docs-example-signing, at the timestamp 1767225600 with the nonce docs-example-nonce-0001; see Authentication and signing.

Headers

Name
X-Api-Key
Type
string, required
Description
The credential id. Sent together with X-Timestamp, X-Nonce and X-Signature.
Name
X-Signature
Type
string, required
Description
Base64 HMAC-SHA256 of the method, the path with its query, X-Timestamp, X-Nonce and the lowercase hex SHA-256 of the raw body, joined by newlines. Compared in constant time; 30 seconds of tolerance; each nonce is used once.
Name
X-Timestamp
Type
string, required
Description
Unix seconds; within 30 seconds of the receiver's clock. Matches ^[0-9]{1,12}$.
Name
X-Nonce
Type
string, required
Description
Single use per credential, kept until the timestamp plus 30 seconds. At least 16 characters. At most 128 characters.

Body

Name
player_id
Type
string, required
Description
The client's own player id, at most 44 characters so that every provider can carry it namespaced. At least 1 character. At most 44 characters.
Name
currency
Type
string, required
Description
One of TRY, EUR, USD, USDT, TON, BTC, AED, AFN, ALL, AMD, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TTD, TWD, TZS, UAH, UGX, USN, UYI, UYU, UYW, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XCG, XOF, XPF, YER, ZAR, ZMW, ZWG.
Name
game_id
Type
string (uuid), required
Description
A UUID v7.
Name
language
Type
string, required
Description
ISO 639-1. Matches ^[a-z]{2}$.
Name
country
Type
string, required
Description
ISO 3166-1 alpha-2. Matches ^[A-Z]{2}$.
Name
device
Type
string, required
Description
One of desktop, mobile.
Name
return_url
Type
string (uri), required
Description
Where the game sends the player back: an https URL only. A javascript:, data: or http: URL is a 400 MALFORMED_REQUEST and is never sent to a provider, and so is one that fails the raw-text check: a non-ASCII host or a mixed-script xn-- label, user information, an empty authority, a space, a backslash or a control or invisible character, raw or percent-escaped. Cocktail receives it as its returnUrl and lobbyUrl, and as its depositUrl on a real launch without deposit_url. Matches ^https://.
Name
deposit_url
Type
string (uri)
Description
The client's cashier, optional and checked like return_url. Cocktail receives it as depositUrl on a real launch; Cocktail requires a depositUrl there, so a real launch without one sends return_url in its place. The other providers' launch calls have no field for it, so they ignore it. Matches ^https://.
Name
mode
Type
string, required
Description
One of real, demo.

Request

POST

/v1/sessions

curl -X POST "https://aggregator.asteriks.casino/v1/sessions" \
  -H "X-Api-Key: test-key-test-key" \
  -H "X-Timestamp: 1767225600" \
  -H "X-Nonce: docs-example-nonce-0001" \
  -H "X-Signature: YbZLU0ILy257UKRsiwpiFYVuvQtQFTR4pLciHtI1t64=" \
  -H "Content-Type: application/json" \
  -d '{
  "player_id": "player-1001",
  "currency": "EUR",
  "game_id": "0199c5a0-0000-7000-8000-000000000002",
  "language": "en",
  "country": "DE",
  "device": "desktop",
  "return_url": "https://casino.example.com/lobby",
  "deposit_url": "https://example.com",
  "mode": "real"
}'

201

Response

The answer is 201 with application/json.

Name
session_id
Type
string (uuid) | null, required
Description
Null in demo mode.
Name
game_url
Type
string (uri), required
Description
The provider's game frame, handed on as the provider wrote it: an https URL that passes the same raw-text check as return_url (ASCII host, no user information, no control, invisible or backslash character, raw or percent-escaped). A provider answer that fails it is a 502 INTERNAL_ERROR, never repaired. Matches ^https://.
Name
expires_at
Type
string (date-time) | null, required
Description
Null in demo mode.

Errors

Each error carries one of these codes in the error object of Errors.

Name
MALFORMED_REQUEST
Type
400
Description
MALFORMED_REQUEST: a body, query or path value fails its schema.
Name
UNAUTHORIZED
Type
401
Description
UNAUTHORIZED: a missing or wrong key, signature, timestamp or nonce.
Name
NOT_FOUND
Type
404
Description
NOT_FOUND: an unknown id, another client's id or an unknown path; one body for every 404.
Name
CURRENCY_NOT_SUPPORTED
Type
422
Description
A launch refused before any session is written or any provider is called: CURRENCY_NOT_SUPPORTED when the provider or the client cannot serve the currency, DEMO_NOT_SUPPORTED when the game has no demo mode.
Name
DEMO_NOT_SUPPORTED
Type
422
Description
A launch refused before any session is written or any provider is called: CURRENCY_NOT_SUPPORTED when the provider or the client cannot serve the currency, DEMO_NOT_SUPPORTED when the game has no demo mode.
Name
INTERNAL_ERROR
Type
502
Description
INTERNAL_ERROR: the provider failed to answer the launch.

Response

{
  "session_id": "0199c5a0-0000-7000-8000-000000000001",
  "game_url": "https://games.example.com/launch/0199c5a0",
  "expires_at": "2026-10-13T12:00:00Z"
}