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 owning the poker runtime.

Status: beta runnable — configuration required. This recipe is runnable for projects with a configured embed product, allowed origin, and scoped management token. 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 keeps management tokens server-side and fails closed when required project/product/origin configuration is missing.

Credential flow: your server holds the pw_mgmt_… management token and creates the embed session. The browser receives the returned launchUrl, which carries a short-lived pwes_… launch secret in the URL fragment. Product keys (pw_test_… / pw_live_…) do not mint embed sessions.

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 embed product visible to your project.
• A service account token stored server-side.
• Management scopes: embeds:read, embed_sessions:create, embed_sessions:read.
• Product access configured 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/management/embed-products	Your server
Create a launch session	POST /api/v1/management/embed-sessions	Your server
Inspect a session	GET /api/v1/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/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.

The runtime open endpoint is a browser-safe companion for this embed flow only. It is not a self-serve launch-ticket, table-state, product-key-authenticated calculation API, or action-submission API.

1. List configured embed products

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

Code
curl https://api.pokerworks.io/api/v1/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/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