# APIリファレンス

このページでは、サードパーティ統合向けのすべてのAPIエンドポイントを一覧表示しています。

:::note[Businessティア以上が必要]
APIは**Businessティア**以上の組織でのみ利用可能です。
:::
## 認証

サードパーティ統合は`x-api-key`ヘッダーで渡す**APIキー**を使用して認証します：

```bash
curl -H "x-api-key: dpk_YOUR_API_KEY" https://app.dailyplay.ai/api/...
```

ダッシュボード管理エンドポイントは代わりに**Clerkベアラートークン**を使用します：

```bash
curl -H "Authorization: Bearer <clerk_token>" https://app.dailyplay.ai/api/...
```

---

## セッションエンドポイント

これらのエンドポイントは、サードパーティ統合がワンタイムセッショントークンを作成・管理するために使用します。

### セッション作成

ゲームまたはストリーム用のワンタイムセッショントークンを作成します。

```
POST /api/org-api-keys?action=create-session
```

**ヘッダー：**

| ヘッダー       | 値                   |
| -------------- | -------------------- |
| `Content-Type` | `application/json`   |
| `x-api-key`    | APIキー（`dpk_...`） |

**ボディ：**

```json
{
  "game_id": 42,
  "stream_id": null,
  "external_ref": "user-12345",
  "metadata": { "campaign": "summer-promo" },
  "expires_in_minutes": 60
}
```

| フィールド           | 型     | 必須   | 説明                         |
| -------------------- | ------ | ------ | ---------------------------- |
| `game_id`            | number | \*     | ターゲットゲームID           |
| `stream_id`          | number | \*     | ターゲットストリームID       |
| `external_ref`       | string | いいえ | 追跡用の参照                 |
| `metadata`           | object | いいえ | 任意のJSONデータ             |
| `expires_in_minutes` | number | いいえ | 有効期限（デフォルト：1440） |

\* `game_id`または`stream_id`の少なくとも1つが必須。

**レスポンス `200`：**

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

---

### セッション検証

セッショントークンが消費せずにまだ有効かどうかを確認します。

```
GET /api/org-api-keys?action=validate-session&token=<uuid>
```

**クエリパラメーター：**

| パラメーター | 型            | 必須 | 説明                       |
| ------------ | ------------- | ---- | -------------------------- |
| `token`      | string (UUID) | はい | 検証するセッショントークン |

**レスポンス `200`：**

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

---

### セッション消費

セッショントークンをアトミックに消費し、再利用不可にします。

```
POST /api/org-api-keys?action=consume-session
```

**ヘッダー：**

| ヘッダー       | 値                 |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

**ボディ：**

```json
{
  "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "player_uuid": "player-uuid-here"
}
```

| フィールド    | 型            | 必須   | 説明                       |
| ------------- | ------------- | ------ | -------------------------- |
| `token`       | string (UUID) | はい   | 消費するセッショントークン |
| `player_uuid` | string        | いいえ | プレイヤーを識別するUUID   |

**レスポンス `200`：**

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

**レスポンス `410`（既に消費済み/期限切れ）：**

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

---

## APIキー管理エンドポイント

これらのエンドポイントは**Clerkベアラートークン**を必要とし、DailyPlayダッシュボードがAPIキーを管理するために使用します。

### APIキー一覧

```
GET /api/org-api-keys?org_id=<id>
```

指定された組織のすべてのAPIキーを返します。

---

### APIキー作成

```
POST /api/org-api-keys
```

**ボディ：**

```json
{
  "org_id": 1,
  "name": "本番CRM",
  "description": "CRMがゲームリンクを発行するために使用",
  "allowed_game_ids": [42, 43],
  "allowed_stream_ids": null,
  "rate_limit_per_minute": 60,
  "rate_limit_per_day": 10000,
  "expires_at": "2027-01-01T00:00:00Z"
}
```

**レスポンス `200`：**

```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "本番CRM",
    "key_prefix": "dpk_a1b2",
    "key": "dpk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
```

:::caution
`key`フィールドは作成レスポンスにのみ含まれます。再取得はできません。
:::
---

### APIキーの更新/取り消し

```
PATCH /api/org-api-keys
```

**ボディ：**

```json
{
  "id": 1,
  "org_id": 1,
  "is_active": false
}
```

`is_active`を`false`に設定してキーを取り消すか、`true`に設定して再アクティブ化します。

---

### APIキーの削除

```
DELETE /api/org-api-keys?id=<id>&org_id=<id>
```

APIキーレコードを完全に削除します。

---

## エラーレスポンス

すべてのエラーレスポンスは以下の形式に従います：

```json
{
  "success": false,
  "error": "何が問題だったかの説明"
}
```

### ステータスコード

| コード | 意味                                                  |
| ------ | ----------------------------------------------------- |
| `200`  | 成功                                                  |
| `400`  | 不正なリクエスト — パラメーターの欠落または無効       |
| `401`  | 認証なし — 無効または取り消されたAPIキー/認証なし     |
| `403`  | 禁止 — キーがリクエストされたリソースにアクセス不可   |
| `410`  | Gone — セッショントークンは既に消費済みまたは期限切れ |
| `429`  | Too Many Requests — レート制限超過                    |
| `500`  | 内部サーバーエラー                                    |