Authentication (JWT)

<aside> ✅

Recommended method. JWT is Splash's standard authentication flow and should be the default for all integrations.

</aside>

The standard flow every integration uses. For every user — logged-in or not — generate a JWT token (HS256), signed with your shared secret. Splash provides a base64-encoded JWT secret (staging and production) during integration.

Token payload

Field	Type	Required	Description
`client`	string	Yes	Unique client ID (for the operator).
`iat`	number	Yes	Issued at (Unix timestamp, seconds).
`exp`	number	Yes	Token expiry (Unix timestamp, seconds).
`sub`	string	Logged-in users	Unique user ID. Send `null` or an empty string for anonymous users.
`username`	string	Optional	User nickname, displayed in public leaderboards.
`email`	string	Optional	User email.
`language`	string	Optional	User language (ISO 639-1).
`country`	string	Optional	User country (ISO 3166-1 alpha-2).
`region`	string	Optional	User region (ISO 3166-2).
`brand`	string	Optional	User brand, to segment between multiple sites.
`currency`	string	Optional	User currency (ISO 4217).
`tags`	string[]	Optional	User tags for customization and restriction logic. See Player Restrictions.
`restricted`	boolean	Optional	Marks the account as restricted. See Player Restrictions.
`…`	—	Optional	Additional parameters, individual per client.

<aside> ⚠️

The same signing key and token structure are reused for the Reporting API — there, the sub claim must contain the external_id of an authorized Back Office user.

</aside>

Example payload:

{
  "client": string,
  "iat": number,
  "exp": number,
  "sub": string,
  "username": string,
  "email": string,
  "language": string,
  "country": string,
  "region": string,
  "brand": string,
  "currency": string,
  "tags": string[],
  "restricted": boolean
}

Launching the game

Redirect to the following URL, or embed it as a full-screen iframe inside your website.

Production

https://{{gameSubdomain}}.splash.tech?token={{token}}&instance={{instance}}

Staging

https://{{gameSubdomain}}-staging.splash.tech?token={{token}}&instance={{instance}}

{{token}} — the JWT generated above.
{{instance}} — an instance identifier agreed during integration, which allows serving multiple games in parallel (e.g. soccer, nfl).
{{gameSubdomain}} — the product subdomain: quiz, fsm, wheel, hub, board, multi-wheel, or streaks. See Reference for the full list.

Custom Authentication

<aside> ⚠️

Last resort only. For platforms that cannot generate a JWT. Use the JWT flow above wherever possible.

</aside>

Custom Authentication