Authentication

Keliplay uses two kinds of credential. Your backend holds an API key and uses it to call the API. For each play, your backend uses that key to ask for a client token, which is the only thing that ever reaches the browser or app.

API keys

Create keys in the dashboard under Settings, then API keys. A key looks like krds_sk_a1b2c3d4e5f6_... and is shown once, when you create it. Store it as a secret on your server. If a key leaks, revoke it in the same screen and create a new one.

Send the key as a bearer token:

curl https://api.keliplay.com/v1/channels \
  -H "Authorization: Bearer $KELIPLAY_API_KEY"

Permissions

Each key has its own set of permissions, chosen when you create it. Give a key only what the system using it needs. A key can only be given permissions that you hold yourself.

Permission	Allows
Issue player tokens	Ask for client tokens. This is all most integrations need.
View campaigns	Read channels, campaigns and their settings.
Create and edit campaigns	Create campaigns and change their details.
Make a campaign live	Activate, pause and schedule campaigns.
Delete a campaign for good	Delete campaigns that have never been played.
Declare a prediction’s real outcome	Mark the correct answer on a prediction campaign.
Create and edit channels	Create, change and delete channels.
Change a game’s rules	Edit a campaign’s game settings.
Change colours, logo and type	Edit branding.
Change player-facing wording	Edit text labels and translations.
Arrange the pre-game page	Edit the page shown before a play.
See entries and winners	Read entries, draws and results.
Run a winner draw	Start a draw.
See reward settings and who received one	Read reward settings and grants.
Set up rewards and the reward page	Change reward tiers and the reward page.
Add, generate and withdraw coupon codes	Manage coupon codes.
Give a reward to a player by hand	Grant a reward through the API.
Browse the media library	List files and folders.
Upload files and organise folders	Upload, import, move and rename files.
Delete files for good	Delete files.
Create and revoke API keys	Manage API keys.
Change where games may load	Manage allowed origins.
Manage webhook endpoints	Create and change webhook endpoints.
View account settings	Read branding and settings.

Managing members and roles is only possible in the dashboard, never with a key.

Client tokens

A client token lets one player make one play of the campaign that is live on a channel. Your backend asks for one each time a player opens the game:

curl -X POST https://api.keliplay.com/v1/auth/session-tokens \
  -H "Authorization: Bearer $KELIPLAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "3f6b1c0a-8e2d-4b7a-9c15-2d4e6f8a0b1c",
    "participantRef": "user_8412",
    "origin": "https://www.example.com"
  }'

Field	Required	Description
`channelId`	Yes	The channel the player is about to play. Keliplay works out which campaign is live.
`participantRef`	Yes	Your own id for the player, up to 200 characters. Use something stable, such as your user id.
`origin`	Yes	Where the game will be shown: your site’s address, or your app as `android:<application id>` or `ios:<bundle id>`. Must be one of your allowed origins.
`ttlSeconds`	No	How long the token stays valid, from 60 to 3600 seconds. The default is 900 (15 minutes).

A successful response is 201:

{
  "clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-10-05T10:15:00.000Z",
  "jti": "6e3c1d0b-2f4a-4c55-9a1e-3b7d9f0c2a11"
}

When nothing is live on the channel, the response is 200 with a null token and the channel’s between-campaigns message. This is not an error. Pass the null token to the embed and it shows the message.

{
  "clientToken": null,
  "betweenCampaigns": {
    "title": "Nothing to play right now",
    "body": "Check back next week for a new game.",
    "imageUrl": null
  }
}

Things to know:

One token, one play. Ask for a new token each time the game is shown. Do not cache tokens between page loads.
Mint just in time. Ask when the page is rendered, not hours before. A token minted just before a campaign changes over still finishes the game it was for.
Play limits apply here. If the player has used all their plays, the request is refused with 409. See Errors and limits.
Only from your backend. The endpoint needs your API key, so it can only be called server side.

Allowed origins

An allowed origin is an address that may embed your games. Tokens are only issued for origins on your list, which stops someone else putting your campaigns on their site with tokens from your account.

Manage the list under Settings, then Allowed origins, or with the API.

Platform	What to add	Example
Web	The scheme and host of your site, without a path. Must be `https`.	`https://www.example.com`
Android app (native SDK)	The app’s application id. Mint tokens with `origin` set to `android:` and the id.	`com.example.app`, minted as `android:com.example.app`
iOS app (native SDK)	The app’s bundle id. Mint tokens with `origin` set to `ios:` and the id.	`com.example.app`, minted as `ios:com.example.app`
Flutter or React Native app in a web view	The site that serves the page the web view opens. See Mobile apps.	`https://app.example.com`

Add each address you serve the game from, including staging sites.