Copy page

Recipes

Embed a club lobby

Use this recipe when a club, company, or community wants a branded page that can open a PokerWorks-powered table without rebuilding poker infrastructure.

Status: Closed beta — approval required. This recipe is runnable only for accounts with an approved embed product and embed access enabled. Player-capable launch remains controlled by PokerWorks; this recipe uses short-lived spectator embed sessions.

Maintained starter: apps/developer-recipe-embed-club-lobby. The starter is also closed beta / approval required and keeps management tokens server-side.

What you build

• A server endpoint in your app that creates a short-lived embed session.
• A page that opens the returned launchUrl.
• A support path that records the embed session id, product key, table id, project id, and environment.

Requirements

• A Console project with the page origin in Allowed origins.
• An approved embed product visible to your account.
• A service account token stored server-side.
• Management scopes: embeds:read, embed_sessions:create, embed_sessions:read.
• Closed-beta embed access enabled for the account or PokerDeck tier.

Public contract

Use the embed-session management contract rather than first-party product routes:

Step	Contract	Caller
Discover approved products	GET /api/v1/developer-api/management/embed-products	Your server
Create a launch session	POST /api/v1/developer-api/management/embed-sessions	Your server
Inspect a session	GET /api/v1/developer-api/management/embed-sessions/{embedSessionId}	Your server
Open the embed	Returned launchUrl with embedSession=..., embedOrigin=..., and #embedLaunchSecret=pwes_...	Browser via the HTML5 client
Redeem the session	POST /api/v1/developer-api/embed-sessions/{embedSessionId}/open	HTML5 client runtime

The HTML5 client consumes the launch secret through the URL fragment, then calls the public runtime open endpoint itself. Your app should open the returned launchUrl, not call the runtime open endpoint directly or mint launch tickets by hand.

1. List approved embed products

Call the management contract from trusted server code with a pw_mgmt_… token. PokerWorks may run the internal CLI during closed-beta proof, but it is not a public install path.

Code
curl https://api.pokerworks.io/api/v1/developer-api/management/embed-products \
  -H "Authorization: Bearer pw_mgmt_…"

Choose the productKey for the lobby or public-ring product you want to embed.

2. Create a spectator embed session

Create sessions on your server, not in a browser. The returned launchUrl carries a reveal-once embedLaunchSecret in the URL fragment so it is not sent to your server logs as a query string.

Code
curl https://api.pokerworks.io/api/v1/developer-api/management/embed-sessions \
  -H "Authorization: Bearer pw_mgmt_…" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "devproj_...",
    "environment": "test",
    "mode": "spectator",
    "productKey": "pokerdeck-club-demo",
    "origin": "https://club.example.com",
    "returnUrl": "https://club.example.com/poker",
    "target": { "kind": "public_ring_product" }
  }'

If your server retries session creation, include a stable x-idempotency-key value for that logical launch request.

The response includes:

Code
{
  "embedSession": {
    "id": "embedsess_...",
    "status": "active",
    "mode": "spectator",
    "projectId": "devproj_...",
    "environment": "test",
    "productKey": "pokerdeck-club-demo",
    "tableId": "table_..."
  },
  "launchSecretTransport": "url_fragment",
  "launchUrl": "https://client.pokerdeck.io/table/table_...?popup=1&brand=pokerdeck&embedSession=embedsess_...&embedOrigin=https%3A%2F%2Fclub.example.com#embedLaunchSecret=pwes_..."
}

The launch URL shape is:

Code
https://client.pokerdeck.io/table/{tableId}?popup=1&brand={brand}&embedSession={embedSessionId}&embedOrigin={encodedOrigin}#embedLaunchSecret=pwes_...

Open launchUrl from your page. Do not persist the fragment secret after the user has launched the embed.

3. Track support evidence

Store only non-secret support evidence:

• embed session id
• project id
• environment
• product key
• table id
• request id from your server logs

Never log pwes_… launch secrets or pw_mgmt_… tokens.

Limitations

• This recipe does not grant arbitrary public write access to tables.
• It does not document PokerDeck BFF routes, Drop In cookies, or quick-game host cookies.
• Player-mode launch needs a separate approved launch/session contract and abuse-control posture.

Related

• Service accounts & management tokens
• Management SDK
• CLI
• Access & limits