Developers

A few lines on your page. Every play on our servers.

Mint a player token on your backend, mount a channel on your page, and get results by signed webhook. The frame, the game and the scoring are ours.

<div id="game"></div>
<script type="module">
  import { mount } from '@keliplay/sdk-web/mount'
  mount('#game', {
    channelId: 'chn_summer',
    clientToken,
  })
</script>

How a play travels

One capsule, five stops.

Your page MOUNTS THE CHANNEL Embed frame RUNS THE GAME Keliplay API DECIDES THE OUTCOME Signed webhook HMAC-SHA256 Your backend VERIFIES AND ACTS Your page MOUNTS THE CHANNEL Embed frame RUNS THE GAME Keliplay API DECIDES THE OUTCOME Signed webhook HMAC-SHA256 Your backend VERIFIES AND ACTS
Your page mounts the channel.

Embed

Three steps. No game code.

  1. Mint a player token

    Your backend asks for a token for one player on one channel. The API key stays on your server. The token covers one campaign, one player and one origin, for up to an hour.

    POST /v1/auth/session-tokens
    Authorization: Bearer <API key>
    Content-Type: application/json
    
    {
      "channelId": "chn_summer",
      "participantRef": "user_8412",
      "origin": "https://shop.example"
    }
  2. Mount the channel

    Point the embed at a channel, not a game. Swap campaigns behind it from the dashboard and this code never changes. Between campaigns the mint returns clientToken: null and the slot shows your own message.

    <div id="game"></div>
    <script type="module">
      import { mount } from '@keliplay/sdk-web/mount'
      const embed = mount('#game', {
        channelId: 'chn_summer',
        clientToken: '…', // from step 1; omit when null
        theme: 'light',
        locale: 'en',
      })
    </script>
    import { KeliplayGame } from '@keliplay/sdk-react'
    
    <KeliplayGame
      channelId="chn_summer"
      clientToken={token}
      onSessionCompleted={({ score }) => track(score)}
      onOutcomeRevealed={({ label, isWin }) => celebrate(isWin)}
    />
  3. Listen on the page

    The embed tells your page when a play ends and what came up, so you can react in your own UI. The authoritative copy still arrives by webhook.

    embed.on('session_completed', ({ sessionId, score }) => {
      // show a thank-you, update a progress bar
    })
    embed.on('outcome_revealed', ({ label, isWin }) => {
      if (isWin) confetti()
    })

Mount options

OptionRequiredDefaultWhat it does
channelId Yes none The only thing a page ever points at.
clientToken No none From step 1. Leave it out when the mint returned null.
theme No none 'light' or 'dark', passed to the frame.
locale No none Passed to the frame.
initialHeight No 420 Height before the game reports its own.
allowImmersive No true Set false on a page whose layout must not be taken over.

Webhooks

Signed results, pushed to you.

Subscribe an endpoint to the events you care about. Pick one to see its payload.

Headers on every delivery

X-Keliplay-Signature
t=<unix seconds>,v1=<hex>
X-Keliplay-Event
The event name.
X-Keliplay-Delivery-Id
Unique per delivery. Use it to ignore repeats.

A failed delivery is tried up to five times in all, with exponential backoff. Timeouts, network errors, 5xx, 408 and 429 are retried; any other 4xx is treated as permanent. Every attempt is in your delivery log.

// POST to your endpoint · X-Keliplay-Event: session_completed
{
  "type": "session_completed",
  "createdAt": "2026-06-03T14:22:07.118Z",
  "data": {
    "gameInstanceId": "gin_01J…",
    "sessionId": "ses_01J…",
    "participantRef": "user_8412",
    "outcome": {
      "id": "seg_3",
      "label": "15% off",
      "isWin": true
    },
    "score": null
  }
}
// Verify before you trust it. Node, with the raw request body.
import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(rawBody, header, secret, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(
    header.split(',').map((p) => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false
  const expected = createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex')
  return v1.length === expected.length &&
    timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}

API keys

Keys that do one job.

Give a key only the permissions its job needs. A key for minting player tokens can't reveal a seed or change your webhooks. Tick a few to build one.

Permissions for this key
New API key 1 permission
kp_sk_3f9a… · minting backend
tokens.mint

This key can mint player tokens. Nothing else.

Documentation

The whole manual is in the docs.

Step-by-step guides, every API endpoint, error codes and limits, and the settings for each game.