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 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 platform gateway at POST /api/v1/auth/session. The platform then:

1. Calls the operator backend at POST /v1/session with the session_request_id
2. The operator validates the session_request_id hasn't expired and hasn't been used, marks it used, and returns an auth_token
3. The platform calls POST /v1/auth with the auth_token to retrieve the bettor's account ID and currency
4. The platform upserts the bettor, stores the auth_token for future wallet calls, and returns a session token to the widget

Step 3: Authenticated API Requests

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

• Validates the session token
• Extracts bettor identity and forwards it as X-Bettor-ID and X-Currency headers to 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 platform /api/v1/auth/session; platform calls operator to validate and retrieve bettor identity
Widget authentication	Session token issued by the platform after operator identity verification
Session token expiration	Configurable per partner
Wallet call auth	HMAC-SHA256 request signing (X-Payload-Signature)