Authentication Flow

The platform uses a two-JWT architecture to separate operator authentication from platform authentication. The operator backend owns the session lifecycle. The platform never calls the operator to create sessions — the operator initiates everything.

Sequence Diagram

How It Works

Step 1: Session Request (Operator-Initiated)

When a bettor wants to access predictions, the operator backend:

1. Authenticates the bettor using the operator's own auth system
2. Generates a session_request_id
3. Returns the prediction widget URL and session_request_id

The operator's platform then loads the widget iFrame, passing the session_request_id as a URL parameter. How the operator implements this internally is up to them.

caution

The session_request_id must be short-lived (recommended: 1–2 minutes) and single-use. Once exchanged for a JWT in Step 2, it must be invalidated. This prevents replay attacks if the URL is intercepted or shared.

Step 2: Session Initialization

The widget calls the operator backend at POST /v1/session with the session_request_id. The operator backend:

1. Looks up the SessionRequest by ID
2. Validates it hasn't expired and hasn't been used
3. Mints a JWT (RS256) containing player claims (player ID, currency, device type)
4. Marks the SessionRequest as used (one-time use)
5. Returns the JWT as auth_token

Step 3: Authenticated API Requests

The widget uses the JWT for all API calls through the platform gateway. The gateway:

• Validates the JWT signature against the operator's JWKS public key
• Forwards authenticated requests to platform backend services

Step 4: Wallet Operations

When the platform needs to debit or credit the bettor (bet placement, settlement), it calls the operator backend server-to-server. The operator backend then executes the actual balance operation on the operator's platform.

• Requests are signed with X-Payload-Signature (HMAC-SHA256)
• Three operations: withdraw (bet placement), deposit (settlement), rollback (reversal)

Key Points

Concern	Mechanism
Session creation	Operator-initiated, implementation is up to the operator
Session exchange	Widget calls /session with one-time session_request_id
Widget authentication	JWT (RS256), validated via JWKS
JWT expiration	Configurable per partner
Wallet call auth	HMAC-SHA256 request signing (X-Payload-Signature)