APIキーの管理

APIキーは、ワークスペースのコンテンツを配信APIから取得するための認証情報です。発行・名前の変更・削除はオーナーが行います。管理画面へのログインには使いません。

キーを発行する

1. 接続したいワークスペースを開きます。
2. 「APIキー」を開き、新しいキーを作成します。
3. 「本番サイト」「ローカル開発」など、用途がわかる名前を入力します。
4. 作成直後に表示されたキーの全文をコピーし、安全な場所に保存します。

全文が表示されるのは作成時だけです。控えを失った場合は新しいキーを発行してください。ワークスペースを切り替えても同じキーを使い回すことはできません。

アプリに設定する

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と、型生成用の_schemaに使用できます。コンテンツの作成・更新・削除を行う公開APIではありません。

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

キーを交換する

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

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

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

接続できないとき

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

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