機能
@nocobase/app-plugin-api-keys は、x-api-key でスクリプトや連携を認証します。リクエストはキーの所有者として動作し、範囲を限定したキーはさらにその範囲で制限されます。
プラグインは認証とキーの API を提供し、個人用の管理画面と業務上の範囲の強制はアプリが担います。
シナリオと例
例：読み取り専用のレポートのスクリプト
- アプリがレポートの権限グループとレコードの範囲を宣言します。
- サインインしたユーザーが利用できる読み取りの権限と有効期限を選び、返されたシークレットを保存します。
- スクリプトはそれを
x-api-keyで送ります。 - 許可された読み取り、拒否される書き込みと範囲外のレコード、取り消し後の拒否を検証します。
有効な権限は、所有者の現在の権限とキーの範囲の共通部分です。範囲を限定したキーを使うには、エンドポイントが認証でそれを受け入れ、認可または該当する範囲のチェックを強制する必要があります。組み込まれていないエンドポイントは、それを拒否します。
開発用のプロンプト（アプリのディレクトリで作業するコーディングエージェント向け）：
API Keys を使って、レポートのスクリプトに有効期限付きの読み取り専用のキーを用意してください。
認証の設定は保ち、レポートの操作とレコードの範囲を宣言し、個人用の作成、ローテーション、
取り消しを組み込んでください。シークレットは発行時とローテーション時にだけ表示し、
ソースやログには決して保存しないでください。許可された読み取り、範囲外の読み取り、書き込み、
古いシークレット、取り消したキーをテストしてください。完了の条件スクリプトが許可されたレポートのレコードだけを読み取り、書き込みと無効になったキーのリクエストが拒否されること。
主な仕組みと実装
以下は、この例での組み込みの領域と、想定される画面の変化です。開発作業を記述したもので、実際のファイル構成はアプリに合わせてください。
| 組み込みの領域 | コードまたは設定の変更 | 画面と動作の変化 |
|---|---|---|
| 認証の設定とプラグインの配列 | apiKey()、apiKeyClient()、マイグレーションを組み合わせる | キーによる認証と管理のエンドポイントを有効にする |
| 個人の設定ページ | 範囲、有効期限、ローテーション、取り消しを組み込む | ユーザーが自分のキーを管理し、シークレットは発行時にだけ表示される |
| レポートの API | 範囲を限定したキーを受け入れ、データのポリシーを適用する | スクリプトのアクセスは、ユーザーの付与とキーの範囲の共通部分になる |
組み込み
両方のランタイムを登録し、マイグレーションを適用します。さらに、/server の apiKey() をサーバーの認証の設定に、/client の apiKeyClient() をクライアントの認証の設定に追加します。先に既定のテンプレートの既存の設定を確認してください。
サーバーで登録するだけではテーブルが作られるだけで、Better Auth のキーのエンドポイントは有効になりません。マイグレーションなしの apiKey() には使うテーブルがありません。キーの管理ページはアプリが所有し、認証のクライアントか /api/apiKeys を使います。
キーを発行して使う
個人のキーの管理には、サインインしたセッションが必要です。キーでほかのキーを管理することはできません。
| エンドポイント | 用途 |
|---|---|
GET /api/apiKeys/scopeOptions | 利用できるグループ、プリセット、有効期限の設定 |
POST /api/apiKeys | キーを作成し、シークレットを一度だけ返す |
GET /api/apiKeys | 所有するキーと範囲を、シークレットなしで一覧表示する |
POST /api/apiKeys/:keyId/rotate | シークレットをローテーションし、古いものをすぐに無効にする |
DELETE /api/apiKeys/:keyId | キーを取り消す |
/main にマウントしたアプリでは次のようにします。
curl -H 'x-api-key: <your-key>' https://app.example.com/main/api/swaggerキーとアプリのアドレスは置き換えてください。API ドキュメントにアクセスできても、そこに記載されたすべてのエンドポイントへのアクセスが付与されるわけではありません。
AI 開発の制約と検証
プラグイン固有の開発の制約
- キーの管理にはサインインしたセッションを使ってください。キーでほかのキーは管理できません。
- 範囲を限定しないキーは読み取り専用ではありません。レポートのエンドポイントは、キーの検証に加えて、操作とレコードを強制する必要があります。
- ローテーション後に古いシークレットがすぐに無効になること、所有者が権限を失ったとき、期限切れ、取り消し後の呼び出しを検証してください。
境界
範囲を限定しないキーは所有者の権限を引き継ぎ、既定で読み取り専用ではありません。所有者が権限を失ったり無効になったりすると、そのキーにも影響します。apiKeys.maxScopedKeyDays は、範囲を限定したキーの有効期間を制限します。ローテーション後は、連携のシークレットを更新してください。
関連：認証、権限管理、プラグインを管理する。
これらはあなたの組み込みの検収の要件であり、実機での検証が完了したことを示すものではありません。実際の変更、実行したチェック、未検証の項目をエージェントに報告させてください。プロジェクトのガイダンス、スキル、共通のチェックについては アプリの開発を続ける と テスト を参照してください。
出典：公開のプラグインの入口と実装。