API キー

API キーの作成

ダッシュボードでアプリを選択
「API Keys」セクションでキー名を入力しスコープを選択
「作成」をクリック — キーはこのとき一度だけ表示されます

スコープ

スコープ	用途	許可される操作
`subscribe_only`	フロントエンド埋め込み	購読の登録・解除のみ
`notify`	サーバーサイド通知送信	通知送信 + 購読操作
`full`	管理用	全操作（アプリ情報取得・統計含む）

使い分けの例

ユーザーのブラウザ (フロントエンド)
  └─ subscribe_only キー → /api/v1/subscriptions (POST) / /api/v1/apps/:appId/subscriptions (POST/DELETE)

自社サーバー (バックエンド)
  └─ notify キー → /api/v1/notify (POST)

CI / 管理スクリプト
  └─ full キー → 全エンドポイント

認証方法

API キーは Authorization: Bearer ヘッダーで送信します。

curl -H "Authorization: Bearer pk_your_key_here" \
  https://api.todoke.dev/api/v1/notify \
  -H "Content-Type: application/json" \
  -d '{"title":"test","body":"test"}'

キーの形式

pk_a1b2c3d4e5f6...  (64文字の16進数)

スコープ × エンドポイント権限マトリクス

各エンドポイントを呼び出せるスコープの一覧です。

エンドポイント	subscribe_only	notify	full
`POST /api/v1/subscriptions`（SDK 用）	✅	✅	✅
`POST` / `DELETE /api/v1/apps/:appId/subscriptions`	✅	✅	✅
`GET /api/v1/vapid-public-key`	✅	✅	✅
`GET /api/v1/stats`	—	✅	✅
`POST /api/v1/notify`・`/notify/batch`	—	✅	✅
`POST /mcp`（MCP エンドポイント）	—	✅	✅
MCP の `list_api_keys` / `create_api_key` / `delete_api_key` ツール	—	—	✅
アプリ作成 `POST /api/v1/apps`	—	—	—（セッション専用。API キーは不可）
アプリ取得・削除・キー発行・削除・一覧・統計 `GET`/`POST`/`DELETE /api/v1/apps*`（作成を除く）	—	—	✅（またはセッション）

キーのライフサイクル

発行時のみ平文表示: 作成直後のレスポンスにのみ平文のキーが含まれます。以後は平文を取得する手段がなく、サーバー側は HMAC-SHA256 + pepper でハッシュ化した値のみを保持し、認証時はハッシュ同士を照合します。
last_used_at の更新: 認証に成功するたびに更新されます。ダッシュボード UI には表示されませんが、CLI の todoke keys list で確認できます。
削除即失効: キーを削除すると即座に無効化されます。そのキーを使っているアプリケーションは認証エラー（INVALID_API_KEY）になります。削除したキーは復元できません。

レート制限

API キー認証を使うエンドポイントは IP アドレス単位で 20 回 / 60 秒のレート制限があります。認証に失敗したリクエストのみカウントされ、正しいキーでの成功リクエストはカウントされません。超過時は 429 RATE_LIMITED が返り、Retry-After: 60 ヘッダーが付与されます。詳細はエラーコード・制限値を参照してください。

発行手段

API キーは次の 3 つの方法で発行できます。

ダッシュボード（本ページ上部の手順）
CLI: todoke keys add
MCP: create_api_key ツール（MCP サーバー。呼び出しには full スコープのキーが必要です）