Quickstart

Create a project in admin, allow the exact site origin (scheme, host, port), and choose a mechanic or legacy template. Anonymous free-play needs only the embed snippet; identified players need a token issued by your backend. Owner preview is in admin.

Server environment

Provide API_BASE, SITE_ORIGIN (an exact allowed site origin), PROJECT_ID, SERVER_API_KEY (scope session:issue) and EXTERNAL_USER_ID through your server environment or secret manager. Never place the API key in HTML, JavaScript, a URL or logs. These commands require curl, Python 3 and jq. Set API_BASE without a trailing slash.

Issue a player token

SESSION_TOKEN=$(python3 -c 'import json,os; print(json.dumps({"project_id":os.environ["PROJECT_ID"],"external_user_id":os.environ["EXTERNAL_USER_ID"]}))' |
  curl --fail-with-body -sS "$API_BASE/v1/server/session-token" \
    -H "Authorization: Bearer $SERVER_API_KEY" \
    -H "Content-Type: application/json" --data-binary @- | jq -er .session_token)
export SESSION_TOKEN

Render this token into data-session-token or pass it to the JS SDK. A missing token starts anonymous play; it does not select preview.

Read progress

curl --fail-with-body -sS "$API_BASE/v1/progress/state" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Origin: $SITE_ORIGIN"

Progress reads use Authorization. The legacy session_token query parameter remains accepted for compatibility, but can expose tokens in URL logs; upgrade old callers. A 401 is an authentication error, never a progress result.

The widget chooses its protocol. Modern games use game runs and server-computed commands; legacy templates use /v1/events. Do not send legacy completion events to finish a modern game.

Rewards

Configure campaigns and a webhook URL in admin. Legacy material outcomes require backend confirmation via /v1/server/events. A modern game win is computed and confirmed by the game server itself. Verify webhooks and fulfil each idempotency_key once. Read the version policy before upgrading a pinned integration.