APIキーの管理

APIキーは、ワークスペースのコンテンツを配信APIから取得するための認証情報です。キーの管理画面はワークスペース設定の「APIキー」タブにあり、オーナーと保守担当にだけ表示されます。管理画面へのログインには使いません。

キーを発行する

1. 接続したいワークスペースを開き、ヘッダーのワークスペース名 →「設定・プラン」を選びます。
2. 「APIキー」タブを開き、「新しいAPIキー」を押します。
3. 「キー名」に「本番サーバー」「ローカル開発」など、用途がわかる名前を入力します。
4. 「読み取り範囲」を「すべてのAPI（今後追加するAPIも含む）」または「選択したAPIのみ」から選びます。限定する場合は1つ以上選択します。
5. 「有効期間」を選び、「作成する」を押します。
6. 「APIキーを保存」に表示されたキーを「コピー」し、安全な場所に保存してから「保存しました」を押します。

キーの全文が表示されるのは作成直後の一度だけです。コピーするまで「保存しました」は押せません。控えを失った場合は新しいキーを発行してください。キーは発行したワークスペースでだけ使えます。

キーの一覧

一覧には、名前・キーの先頭（xxxx••••••）・読み取り範囲（「すべてのAPI」または「n個のAPI」）・有効期間・作成日・最終使用が並びます。

行の「⋯」から「キーを編集」「キーの先頭をコピー」「削除」を選べます。行を押しても編集画面が開きます。

アプリに設定する

CLIで初期化する場合は、CLIのinitの入力にキーを渡します。手動の場合は、実行環境の非公開の環境変数に設定します。

GENKO_API_KEY=ここに発行したキーを設定

const apiKey = process.env.GENKO_API_KEY;if (!apiKey) throw new Error("GENKO_API_KEYを設定してください。");

APIへ直接接続するときは、X-API-KEYヘッダーに付けます。URLのクエリパラメータではありません。

curl 'https://api.genko.me/v1/your-workspace/blog' \  -H "X-API-KEY: ${GENKO_API_KEY}"

.env.localをGitに追加しないでください。本番環境のキーはホスティング先の環境変数として登録します。NEXT_PUBLIC_などの公開用の名前や、ブラウザへ送るJavaScriptには含めません。ブラウザで使うキーを公開する場合は、読み取り専用として扱い、公開済みコンテンツだけを取得できる構成にしてください。配信APIの CORS * はブラウザからの利用を許すための仕様で、キーの秘匿やオリジン制限にはなりません。

キーがアクセスできる範囲

キーは発行元のワークスペースに紐づきます。そのワークスペースの配信APIと、型生成用の_schemaに使用できます。コンテンツの作成・更新・削除を行う公開APIではありません。

「すべてのAPI」は今後追加するAPIも含みます。「選択したAPIのみ」では、指定したAPIの一覧・詳細・オブジェクトだけを取得できます。範囲外は404となり、_schemaにも含まれません。参照フィールドの範囲外APIは展開せず、元の参照IDを返します。

読み取り範囲は「キーを編集」で変更できます。変更は保存後のリクエストから適用されます。名前やエンドポイントを変更しても同じAPIへの許可は維持されますが、削除して同じエンドポイントで作り直したAPIには引き継がれません。

通常は公開コンテンツを取得します。下書きの取得には、別途そのコンテンツのdraftKeyが必要です。下書きプレビューを参照してください。

有効期間

作成時は「30日」「90日」「1年」「無期限」から選ぶか、「期間を指定」でカレンダーから開始日と終了日を選びます。既定は今日からの90日です。期間を指定する場合は、今日から5年以内の日付を選べます。開始日と終了日を同じ日にすることもできます。

日付はアカウントに設定したタイムゾーンで数えます。開始日の0:00から終了日の23:59まで使えます。

開始日より前のリクエストは拒否されます。切り替えの日が決まっている場合は、先にキーを発行して環境変数に設定しておけます。無期限のキーは削除するまで使われ続けるため、使う期間が決まっている場合は期限を付けてください。

期間を延ばす・変更する

期限が切れたキーも、一覧に「期限切れ」として残ります。「キーを編集」の「有効期間」で新しい期間を選び、「保存」を押すと再び使えます。変更しない場合は「変更しない」を選んだままにします。キー本体は変わらないため、環境変数を更新する必要はありません。

期限前のお知らせメール

有効期限の7日前になると、ワークスペースのオーナーと保守担当全員に「genko.meのAPIキーの有効期限が近づいています」というメールが届きます。メールにはワークスペース名・キー名・キーの先頭・有効期限が記載されます。

メールの「有効期間を変更する」を押すと、そのキーの編集画面が開きます。ログインしていない場合は、ログイン後に編集画面へ進みます。キーがすでに削除されている場合は、その旨が表示されます。

作成日から有効期限までが7日以内のキーには、このメールは送られません。有効期間を変更して期限が変わると、新しい期限の7日前にもう一度届きます。

キーを交換する

運用中のキーを交換するときは、次の順番で行います。

1. 同じワークスペースで新しいキーを発行します。
2. 利用するすべてのアプリ・ビルド環境の環境変数を更新します。
3. 必要な再起動・再デプロイを行い、取得できることを確認します。
4. 古いキーを「削除」します。

漏えいが疑われる場合は、該当キーの削除を優先してください。削除したキーを使っているアプリは認証エラーになるため、新しいキーへ切り替えます。

接続できないとき

401はキーの未設定・無効化のほか、有効期間の外にあるキーでも返ります。期間外の場合は、次のメッセージで区別できます。

• 開始日より前: This API key's validity period has not started yet.
• 終了日を過ぎた: This API key has expired.

403は接続先ワークスペースとの不一致を確認します。429は同一キーのレート制限です。標準の上限は1分間に300リクエストで、_schemaの取得も認証対象です。

詳しい対処はエラーと制限を参照してください。