# 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.

:::caution[I-enable ang "Require API Session Token"]
Para magkabisa ang session tokens, kailangan mong i-enable
ang setting na **"Require API Session Token"** sa bawat game o stream sa **Configuration** tab.
Kung hindi naka-enable ang setting na ito, magiging playable ang mga laro nang walang token restrictions.
:::

## 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:

```bash
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

```json
{
  "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:

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

### Response

```json
{
  "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:

```bash
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

```json
{
  "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:

```json
{
  "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                                    |