# セッショントークン

セッショントークンは、ゲームまたはストリームの1回のプレイを許可する**使い捨てトークン**です。各トークンが1回のみ消費されることを保証し、不正利用を防ぎます。

:::caution[「APIセッショントークンを必須にする」を有効にしてください]
セッショントークンを有効にするには、各ゲームまたはストリームの**設定**タブで**「APIセッショントークンを必須にする（Require
API Session
Token）」**設定を有効にする必要があります。この設定が無効の場合、ゲームはトークンの制限なしにプレイ可能になります。
:::

## トークンのライフサイクル

セッショントークンは以下の状態を経ます：

```
active  →  consumed   (ユーザーがゲームをプレイ)
        →  expired    (トークンの有効期限切れ)
        →  revoked    (手動で無効化)
```

## ステップ1：セッションの作成

APIキーを使用してサーバーからセッション作成エンドポイントを呼び出します：

```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
  }'
```

### リクエストパラメーター

| パラメーター         | 型     | 必須                                 | 説明                                                  |
| -------------------- | ------ | ------------------------------------ | ----------------------------------------------------- |
| `game_id`            | number | `game_id`または`stream_id`のどちらか | アクセスを許可するゲーム                              |
| `stream_id`          | number | `game_id`または`stream_id`のどちらか | アクセスを許可するストリーム                          |
| `external_ref`       | string | いいえ                               | 追跡用の参照ID（例：ユーザーID、注文ID）              |
| `metadata`           | object | いいえ                               | 追跡用の任意のJSONデータ                              |
| `expires_in_minutes` | number | いいえ                               | トークンの有効期限（分）（デフォルト：1440 = 24時間） |

### レスポンス

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

## ステップ2：ユーザーのリダイレクト

セッショントークン付きのURLを構築し、エンドユーザーをリダイレクトします：

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

ストリームの場合：

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

## ステップ3：トークンの検証

プレイを許可する前に、トークンがまだアクティブで期限切れでないことを検証します：

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

### レスポンス

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

## ステップ4：トークンの消費

ユーザーがプレイを開始すると、トークンは消費され再利用不可になります：

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

### 成功レスポンス

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

### 既に消費済みまたは期限切れ

トークンが既に使用されている、または期限切れの場合、APIは`410 Gone`ステータスを返します：

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

## トークンのプロパティ

| プロパティ              | 説明                                                         |
| ----------------------- | ------------------------------------------------------------ |
| `token`                 | UUID v4識別子 — ゲームURLに渡される                          |
| `stream_id` / `game_id` | ターゲットリソース（少なくとも1つ必須）                      |
| `external_ref`          | あなたのシステムとの相関用の参照ID                           |
| `metadata`              | 作成時に添付された任意のJSONペイロード                       |
| `status`                | 現在の状態：`active`、`consumed`、`expired`、または`revoked` |
| `expires_at`            | トークンが自動的に期限切れになる日時                         |

## 有効期限

- `expires_in_minutes`が指定されない場合、トークンのデフォルト有効期限は**24時間**
- 期限切れトークンはバックグラウンドプロセスで自動クリーンアップ
- 時間に敏感なユースケースでは最短1分の有効期限を設定可能

## エラーハンドリング

| ステータスコード | 意味                                            |
| ---------------- | ----------------------------------------------- |
| `200`            | トークンが有効/操作成功                         |
| `400`            | パラメーターの欠落または無効                    |
| `401`            | 無効または取り消されたAPIキー                   |
| `403`            | APIキーがリクエストされたリソースにアクセス不可 |
| `410`            | トークンは既に消費済みまたは期限切れ            |
| `429`            | レート制限超過                                  |