Session Tokens

Session tokens are one-time-use tokens that grant a single play of a game or stream. They prevent abuse by ensuring each token can only be consumed once.

Token Lifecycle

A session token goes through the following states:

active  →  consumed   (user played the game)
        →  expired    (token passed its expiration time)
        →  revoked    (manually invalidated)

Step 1: Create a Session

Call the session creation endpoint from your server with your API key:

curl -X POST https://app.dailyplay.ai/api/org-api-keys?action=create-session \
  -H "Content-Type: application/json" \
  -H "x-api-key: dpk_YOUR_API_KEY" \
  -d '{
    "game_id": 42,
    "external_ref": "user-12345",
    "metadata": { "campaign": "summer-promo" },
    "expires_in_minutes": 60
  }'

Request Parameters

Parameter	Type	Required	Description
game_id	number	One of game_id or stream_id	The game to grant access to
stream_id	number	One of game_id or stream_id	The stream to grant access to
external_ref	string	No	Your reference ID for tracking (e.g., user ID, order ID)
metadata	object	No	Arbitrary JSON data for your own tracking
expires_in_minutes	number	No	Token expiry in minutes (default: 1440 = 24 hours)

Response

{
  "success": true,
  "data": {
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "stream_id": null,
    "game_id": 42,
    "expires_at": "2026-02-17T12:00:00.000Z",
    "external_ref": "user-12345"
  }
}

Step 2: Redirect the User

Build a URL with the session token and redirect the end user to it:

https://app.dailyplay.ai/play/game/42?session_token=a1b2c3d4-e5f6-7890-abcd-ef1234567890

For streams:

https://app.dailyplay.ai/play/stream/10?session_token=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Step 3: Validate the Token

Before allowing play, the token is validated to ensure it is still active and not expired:

curl https://app.dailyplay.ai/api/org-api-keys?action=validate-session&token=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

{
  "success": true,
  "data": {
    "valid": true,
    "status": "active",
    "stream_id": null,
    "game_id": 42,
    "expires_at": "2026-02-17T12:00:00.000Z",
    "external_ref": "user-12345",
    "metadata": { "campaign": "summer-promo" }
  }
}

Step 4: Consume the Token

When the user starts playing, the token is consumed so it cannot be reused:

curl -X POST https://app.dailyplay.ai/api/org-api-keys?action=consume-session \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "player_uuid": "player-uuid-here"
  }'

Success Response

{
  "success": true,
  "data": {
    "session_id": 1,
    "org_id": 5,
    "stream_id": null,
    "game_id": 42,
    "external_ref": "user-12345",
    "metadata": { "campaign": "summer-promo" }
  }
}

Already Consumed or Expired

If the token has already been used or has expired, the API returns a 410 Gone status:

{
  "success": false,
  "error": "Session is invalid, already consumed, or expired"
}

Token Properties

Property	Description
token	UUID v4 identifier — passed in the game URL
stream_id / game_id	The target resource (at least one is required)
external_ref	Your reference ID for correlating with your system
metadata	Arbitrary JSON payload you attached at creation
status	Current state: active, consumed, expired, or revoked
expires_at	When the token will automatically expire

Expiration

• Tokens default to a 24-hour expiry if expires_in_minutes is not specified
• Expired tokens are automatically cleaned up by a background process
• You can set expiry as short as 1 minute for time-sensitive use cases

Error Handling

Status Code	Meaning
200	Token is valid / operation succeeded
400	Missing or invalid parameters
401	Invalid or revoked API key
403	API key does not have access to the requested resource
410	Token is already consumed or expired
429	Rate limit exceeded