Launch Tokens

Your backend mints Phoenix Prediction launch tokens. The browser receives a ready-to-use token, but it never sees your private signing key.

Phoenix Prediction launch tokens are EdDSA JWTs signed with your Ed25519 private key. Phoenix verifies each token with the public key registered for the environment the token names in env. That is one key, or two while you rotate; a token signed with either verifies (see Environments and Rotating a Key).

Claims

The JWT header is { "alg": "EdDSA", "typ": "JWT" } plus an optional kid (see Key Id).

Visitor or Player

sub decides who the session belongs to, and nothing else does:

When a visitor taps a player-only action, the embed asks your page to sign the user in (see Host SDK).

Token Limits

Phoenix refuses a token that breaks any of these limits. The launch does not start, and the answer names the limit that failed (see Refusals You Can Read).

A day is the ceiling, not a target. Tokens are bearer credentials: anyone holding one can launch as that player until it expires, so mint them for minutes. Read Sessions and Token Refresh before choosing a lifetime: the token's lifetime also decides how long a dropped connection can come back without a reload.

Refusals You Can Read

The embed's boot configuration call (GET /embed/api/config) answers a refused launch with a JSON body that names the reason, so you can see it in the browser's network panel while you integrate:

{
  "error": "unknown_key",
  "message": "The kid header names none of the environment's keys.",
  "details": { "kid": "0123456789abcdef" }
}

Branch on error. message is a sentence for a developer, and details names what was wrong (it is {} when there is nothing to add). The checks run in the order of this table and the first one that fails is the answer:

An operator code and an environment appear in every launch URL, so anyone can learn that one does not exist. Every reason from token_expired down is told only for a token whose signature verified, so a forged token learns nothing about your environment's status, your standing, your players or your currencies.

The live connection applies the same token checks but gives no reason: a refused connection is a plain failed WebSocket. The embed reports the reason it read here to your page (see Parent Bridge).

Key Id (kid)

kid is an optional JWT header. When you send it, it must be the id of one of the Ed25519 public keys registered for the token's env, and only that key is tried; a token whose kid names any other key is refused with unknown_key. It is a useful guard against signing with the wrong environment's key, and during a rotation it says which of the two keys signed the token.

The id is the first 8 bytes of the SHA-256 of the raw 32-byte public key, as 16 lowercase hex characters. In Node:

import { createHash, createPublicKey } from 'node:crypto';

export function keyId(keyPem: string) {
  const spki = createPublicKey(keyPem).export({ format: 'der', type: 'spki' });
  const raw = spki.subarray(spki.length - 32);
  return createHash('sha256').update(raw).digest('hex').slice(0, 16);
}

createPublicKey accepts either the public key PEM you registered or your private key PEM (it derives the public half), so both give the same id.

Token Ids (jti)

jti is optional. When you send it, Phoenix remembers it per operator and environment until the token expires, and applies one rule: a jti names one token.

• The same token presented again is accepted. The iframe presents its token several times (the boot configuration, the live connection, and every reconnect), so Phoenix does not treat a second sight of the same token as a replay.
• A different token that carries a jti Phoenix has already seen is refused until the first token expires.

Generate a fresh random jti (a UUID) for every token you mint, including every refresh. A fixed value such as the player id or the session id makes every token after the first one be refused.

jti stops two different tokens sharing an id. It does not make a token single-use: a copied token keeps working until exp, so keep tokens short-lived and out of logs.

Environment Claim

env is not just metadata. It selects which of your operator environments receives the launch, and so which public keys verify the token, which sites may frame the embed and which wallet it moves money with.

Mint sandbox tokens only for testing traffic, and prod tokens only from production systems that are ready for real players.

Token Shapes

{
  "iss": "acme",
  "env": "sandbox",
  "currency": "KES",
  "iat": 1779100000,
  "exp": 1779100900
}

{
  "iss": "acme",
  "env": "sandbox",
  "sub": "operator-player-123",
  "currency": "KES",
  "name": "Player Name",
  "avatar": { "kind": "none" },
  "iat": 1779100000,
  "exp": 1779100300
}

Avatar Values

Session Currency

Phoenix is multi-currency. The currency claim selects the money currency for the whole session: the prices and volumes a visitor sees, and the books a player trades, are all in that currency.

• currency must be one of your operator's currencies.
• It is required on every token, including for single-currency operators.
• Set it per launch to route a player to a specific currency (for example a KES player and a USD player of the same operator).

Player Language

The optional language claim states the language the embed shows. Send it only when your site has its own language switcher, so the player's language has one owner:

• With language, your site owns it. The embed opens in that language if your operator offers it, else in your default language, and shows no language picker of its own. When the player switches language on your site, call setLanguage on the host SDK; you do not need a new token. A code your operator does not offer never refuses the launch.
• Without language, the embed owns it. It shows a picker when your operator offers two or more languages, and remembers the player's choice for their next launch.

Codes are short language codes (en, fr, sw); a regional form such as fr-FR is read as fr. See Languages for the full rules.

Node.js Example

import { createHash, createPublicKey, randomUUID } from 'node:crypto';
import { SignJWT, importPKCS8 } from 'jose';

const privateKeyPem = process.env.PHOENIX_PREDICTION_OPERATOR_PRIVATE_KEY_PEM!;
const key = await importPKCS8(privateKeyPem, 'EdDSA');

const kid = (() => {
  const spki = createPublicKey(privateKeyPem).export({ format: 'der', type: 'spki' });
  const raw = spki.subarray(spki.length - 32);
  return createHash('sha256').update(raw).digest('hex').slice(0, 16);
})();

export async function mintPlayerToken(player: {
  id: string;
  name: string;
  phoenixEnv: 'sandbox' | 'prod';
  currency: string; // one of your operator's currencies, e.g. 'KES'
  language?: string; // only if your site has its own language switcher
}) {
  const now = Math.floor(Date.now() / 1000);

  return new SignJWT({
    env: player.phoenixEnv,
    sub: player.id,
    currency: player.currency,
    name: player.name,
    avatar: { kind: 'none' },
    ...(player.language ? { language: player.language } : {}),
  })
    .setProtectedHeader({ alg: 'EdDSA', kid })
    .setIssuer('acme')
    .setJti(randomUUID())
    .setIssuedAt(now)
    .setExpirationTime(now + 30 * 60)
    .sign(key);
}

Compute now inside the function, on every call. A value computed once at startup would give every later token an expiry in the past.

Lifetime, Reconnects and Refresh

Phoenix issues no session token of its own. The launch token is the session's credential for its whole life: the embed presents it again on every reconnect after a network drop. A connection that is already open stays open after the token expires, but a reconnect with an expired token is refused.

So the lifetime you choose is a trade-off:

• A short token (minutes) limits what a leaked token can do, but a player whose connection drops after it expires sees "Your session ended" until your page gives the embed a fresh token.
• Your page can hand over a fresh token at any time without a reload: the embed warns you a minute before expiry (token.expiring) and again if the session ends (session.expired). Answer both with setToken.

Sessions and Token Refresh covers the events and the code.