# API Keys

Pinapayagan ng API keys ang iyong server na mag-authenticate sa DailyPlay API. Ginagawa ang keys mula sa
dashboard at ginagamit sa `x-api-key` header kapag gumagawa ng API calls.

:::note[Business Tier Required]
Available lang ang API keys para sa mga organisasyon sa **Business
tier** o mas mataas.
:::

## Paglikha ng API Key

1. Mag-log in sa DailyPlay dashboard
2. Mag-navigate sa **Connect → API Keys** sa sidebar
3. I-click ang **Create API Key**
4. Maglagay ng pangalan (hal., "Production CRM") at opsyonal na description
5. Opsyonal na i-enable ang **MCP scopes** kung gagamitin ang key para sa AI agent (tingnan sa ibaba)
6. Opsyonal na magtakda ng expiration date
7. I-click ang **Create**

:::caution
Kopyahin agad ang generated key — isang beses lang ito ipinapakita at hindi na mababawi mamaya.
:::
Ang format ng key ay `dpk_<40 hex characters>`, halimbawa:

```
dpk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
```

## Key Scoping

Maaaring i-scope ang API keys para limitahan kung aling resources ang maa-access nila:

| Scope                   | Paglalarawan                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| **All games & streams** | Default — maaaring gumawa ang key ng sessions para sa anumang resource sa org |
| **Specific games**      | Limitahan sa listahan ng game IDs                                    |
| **Specific streams**    | Limitahan sa listahan ng stream IDs                                  |

Ang pagtatangkang gumawa ng session para sa resource sa labas ng scope ng key ay nagbabalik ng `403 Forbidden`
error.

## MCP Scopes

Bukod sa game/stream allowlists, maaaring magdala ang keys ng **MCP scopes** na nagbibigay ng access sa remote
[MCP server](/fil/api/mcp/). Deny-by-default ang scopes:

| Scope | Nagbibigay |
| --- | --- |
| _(none)_ | Session-token minting lang (legacy / REST behavior) |
| `mcp:templates:read` | Maglista at mag-inspect ng templates |
| `mcp:games:read` / `mcp:games:write` | Magbasa o gumawa/mag-update ng games at prizes |
| `mcp:streams:read` / `mcp:streams:write` | Magbasa o gumawa/mag-update ng streams |
| `mcp:connections:read` / `mcp:connections:write` | Pamahalaan ang org integrations |
| `mcp:analytics_providers:read` / `mcp:analytics_providers:write` | Pamahalaan ang client-side analytics providers |
| `mcp:gallery:read` / `mcp:gallery:write` | Maglista ng gallery media o magtanggal ng unused assets |
| `mcp:vouchers:read` / `mcp:vouchers:write` | Magbasa o pamahalaan ang voucher sets at codes |
| `mcp:reports:read` | Magbasa ng org analytics at reports |
| `mcp:ai` | Brand extract, funnel wizard, image generation |
| `mcp:sessions:write` | Mag-mint ng play sessions sa pamamagitan ng MCP |

Maaari mong i-edit ang MCP scopes mamaya mula sa API Keys list nang hindi nire-rotate ang key. Tingnan ang
[MCP Tools](/fil/api/mcp-tools/) para sa buong tool list.

## Rate Limits

Ang bawat API key ay may configurable rate limits:

| Limit      | Default | Paglalarawan                 |
| ---------- | ------- | --------------------------- |
| Per minute | 60      | Maximum requests bawat minuto |
| Per day    | 10,000  | Maximum requests bawat araw    |

Kapag nalampasan ang rate limit, nagbabalik ang API ng `429 Too Many Requests` response.

## Pag-revoke ng Key

Maaari mong i-revoke ang API key anumang oras mula sa dashboard:

1. Pumunta sa **Connect → API Keys**
2. Hanapin ang key sa listahan (nakikilala sa `dpk_****` prefix at pangalan nito)
3. I-click ang revoke action

Ang pag-revoke ng key:

- Agad na hinaharang ang lahat ng future API calls gamit ang key na iyon
- **Hindi** nag-i-invalidate ng session tokens na nagawa na gamit ang key
- Pinapanatili ang audit trail — napanatili ang key record pero minarkahan bilang inactive
- Maaaring i-reactivate kung kailangan

## Seguridad

- **Hash ang keys gamit ang SHA-256** bago iimbak — hindi mababawi ang raw keys mula sa database
- Ang unang 8 characters (`dpk_xxxx`) lang ang naka-store sa plaintext para sa identification
- Maaaring itakda ang keys na **awtomatikong mag-expire** sa partikular na petsa
- Nila-log ang lahat ng key usage para sa auditing purposes

## Pamamahala ng Keys sa pamamagitan ng API

Maaari mo ring pamahalaan ang API keys nang programmatically gamit ang authenticated requests (Clerk bearer token):

| Method   | Endpoint                                | Paglalarawan                   |
| -------- | --------------------------------------- | ----------------------------- |
| `GET`    | `/api/org-api-keys?org_id=<id>`         | Maglista ng lahat ng API keys para sa org  |
| `POST`   | `/api/org-api-keys`                     | Gumawa ng bagong API key          |
| `PATCH`  | `/api/org-api-keys`                     | Mag-update o mag-revoke ng API key   |
| `DELETE` | `/api/org-api-keys?id=<id>&org_id=<id>` | Permanenteng tanggalin ang API key |

### Gumawa ng Key (API)

```bash
curl -X POST https://app.dailyplay.ai/api/org-api-keys \
  -H "Authorization: Bearer <clerk_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 1,
    "name": "Production CRM",
    "description": "Used by the CRM to issue game links",
    "allowed_game_ids": [42, 43],
    "rate_limit_per_minute": 60,
    "rate_limit_per_day": 10000,
    "expires_at": "2027-01-01T00:00:00Z"
  }'
```

Kasama sa response ang raw key (isang beses lang ipinapakita):

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