Session Tokens

Ang session tokens ay one-time-use tokens na nagbibigay ng isang play ng game o stream. Pinipigilan nila ang abuse sa pamamagitan ng pagsisiguro na isang beses lang maaaring konsumin ang bawat token.

Token Lifecycle

Dumadaan ang session token sa mga sumusunod na estado:

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

Hakbang 1: Gumawa ng Session

Tawagan ang session creation endpoint mula sa iyong server gamit ang iyong 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	Paglalarawan
`game_id`	number	Isa sa `game_id` o `stream_id`	Ang larong bibigyan ng access
`stream_id`	number	Isa sa `game_id` o `stream_id`	Ang stream na bibigyan ng access
`external_ref`	string	No	Ang iyong reference ID para sa tracking (hal., user ID, order ID)
`metadata`	object	No	Arbitrary JSON data para sa sarili mong tracking
`expires_in_minutes`	number	No	Token expiry sa minuto (default: 1440 = 24 oras)

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"
  }
}

Hakbang 2: I-redirect ang User

Gumawa ng URL na may session token at i-redirect ang end user dito:

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

Para sa streams:

https://app.dailyplay.ai/stream/<org-slug>/<stream_id>?session_token=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Hakbang 3: Beripikahin ang Token

Bago payagan ang play, bineberipika ang token para masiguro na active pa ito at hindi pa 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" }
  }
}

Hakbang 4: Konsumin ang Token

Kapag nagsimulang maglaro ang user, kinokonsumo ang token para hindi ito muling magamit:

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 o Expired

Kung nagamit na o nag-expire na ang token, nagbabalik ang API ng 410 Gone status:

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

Token Properties

Property	Paglalarawan
`token`	UUID v4 identifier — ipinapasa sa game URL
`stream_id` / `game_id`	Ang target resource (kailangan ang hindi bababa sa isa)
`external_ref`	Ang iyong reference ID para i-correlate sa iyong sistema
`metadata`	Arbitrary JSON payload na in-attach mo sa creation
`status`	Kasalukuyang estado: `active`, `consumed`, `expired`, o `revoked`
`expires_at`	Kailan awtomatikong mag-e-expire ang token

Expiration

Default na 24-hour expiry ang tokens kung hindi tinukoy ang expires_in_minutes
Awtomatikong nililinis ang expired tokens ng background process
Maaari mong itakda ang expiry nang kasingikli ng 1 minuto para sa time-sensitive use cases

Error Handling

Status Code	Kahulugan
`200`	Valid ang token / naging successful ang operation
`400`	Missing o invalid parameters
`401`	Invalid o revoked API key
`403`	Walang access ang API key sa requested resource
`410`	Na-consume na o nag-expire na ang token
`429`	Nalampasan ang rate limit