構成プランを適用
POST /v1/config-plans/{plan_id}:apply · 権限 config:write、プランの読み取り権限と、変更される各種類の書き込み権限
保存済みのプランを環境に適用します。すべての変更は1つのトランザクションで書き込まれ、1つでも失敗した場合は何も保持されません。プランは一度だけ適用できます。
リクエスト
| パラメーター | 説明 |
|---|---|
plan_id |
プランの ID、cfgp_…。 |
本文は省略可能です。
| フィールド | 説明 |
|---|---|
resolved_secrets |
requires_secret: true を持つ変更ごとに、secret_ref の name → value のオブジェクトを指定します（例: KEENAUTH_CONNECTION_GITHUB_CLIENT_SECRET）。値は最大 8 KiB です。プランによって保存、ログ記録、返却されることはありません。 |
confirm_deletions |
確認する削除の <kind>/<key> のリスト（例: connection/legacy）。プランの deletion_requires_confirmation 警告に、それが必要な削除が一覧されます。 |
sp_host |
環境のサービスプロバイダーのホスト（例: login.example.com）。プランがエンタープライズ接続の OIDC 素材を作成する場合にのみ必要です（コールバック https://<sp_host>/sso/<connection id>/callback はこのホストから固定されます）。必要のないリクエストで送信してはなりません。 |
- 書き込み権限は
environment-settings:write、identity-settings:write、attack-protection:write、branding:write（brandingおよびapplication_branding用）、connections:write、apis:write、roles:write、applications:writeです。変更（no_op以外）がある種類についてのみ必要です。 - 書き込み前に対象が再読み取りされます。計画された任意のリソースのバージョン、またはプランの種類の内容が、プラン作成後に変わっていた場合は、何も書き込まれず、プランは
conflictedになり、リクエストは409 config_conflictで失敗します。新しいプランを作成してください。pruneを指定すると、計画されたリソースを参照する種類も比較され、リソース間の参照が再確認されます。参照が壊れている場合も、プランはconflictedになります。 - 接続の削除、または過去 30 日間にトークンを受け取ったアプリケーションの削除は、
confirm_deletionsで繰り返す必要があります。そうしないと、リクエストは409 deletion_not_confirmedで失敗し、プランはplannedのままです。 - エンタープライズ接続の OIDC 素材（
spec.oidc）とそのクライアントシークレットは、接続レコードの後にフェデレーションサービスへ書き込まれます。この2回目の書き込みが拒否された場合、プランはplannedのままで、接続レコードは既に存在している可能性があります。新しいプランでは不足している素材のみが書き込まれます。spec.oidc（null）は素材を変更しません。ソーシャル接続のクライアントシークレットはまだ書き込めません。そのようなrequires_secretの変更を含むプランは、シークレットの確認後に501 not_implementedを返します。何も書き込まれません。 Idempotency-Keyがサポートされています。可能な場合は、本文にシークレットを含めずに送信してください。キーのレコードには本文のハッシュが保持されます。
レスポンス
200 OK と Cache-Control: no-store を返します。構成プランの取得 と同じ形式のプランで、status: applied と applied_at を含みます。
変更前の影響を受けるリソースの構成は、リビジョンとして保持されます（環境ごとに最新 50 件、最長 90 日）。適用時には、環境の管理ログに config.applied のエントリが 1 件書き込まれ、作成、更新、削除、変更なしのリソース数が記録されます。変更された各リソースも、それぞれ独自のエントリを書き込みます。
エラー
| HTTP | code | 発生条件 |
|---|---|---|
| 400 | malformed_request, unknown_field |
本文が JSON ではないか、resolved_secrets、confirm_deletions、sp_host 以外のフィールドがあります。 |
| 401 | unauthenticated |
認証情報がない、無効、または取り消されています。 |
| 403 | insufficient_permissions |
認証情報に必要な権限がありません。required_permissions にすべてが一覧されます。 |
| 404 | not_found |
プランが存在しない、別の環境に属する、または削除されています。 |
| 409 | config_conflict |
プラン作成後に対象が変更されました。プランは現在 conflicted です。 |
| 409 | config_plan_not_applicable |
プランは既に適用されているか conflicted であるか、別のリクエストが現在適用中です（plan_status: applying）。plan_status にステータスが示されます。 |
| 409 | deletion_not_confirmed |
保護された削除が confirm_deletions にありません。unconfirmed_deletions に一覧されます。 |
| 409 | conflict |
別のリソースが変更の一意の値を既に使用しています（errors[].pointer は /changes/<i>/spec/<field>、コード duplicate）。プランは planned のままです。 |
| 409 | connection_in_use |
削除対象の接続がまだ使用中です。プランは planned のままです。 |
| 409 | connection_test_required |
変更で enterprise 接続 active を作成するか、成功したテストサインインなしで有効化しています（errors[].pointer は /changes/<i>/spec、コード test_required）。プランは planned のままです。 |
| 410 | config_plan_expired |
プランの有効期限が過ぎました。新しいプランを作成してください。 |
| 413 | config_document_too_large |
変更、またはそのために保持されるリビジョン（最大 10 MiB）が大きすぎて、1 回のリクエストで適用できません。プランの種類を減らしてください。 |
| 422 | validation_failed |
下記を参照してください。 |
| 422 | policy_conflict |
変更が環境のポリシーと競合しています。プランは planned のままです。 |
| 429 | rate_limited |
config_plan のレート制限（プラン作成と共有）を超えたか、この環境で同時に計算または適用中のプランが多すぎます。プランは planned のままです。Retry-After 期間の後に再試行してください。 |
| 501 | not_implemented |
プランはソーシャル接続のクライアントシークレットを必要としますが、まだ書き込めません。 |
| 503 | service_unavailable |
依存先（ディレクトリ、またはエンタープライズ OIDC 素材の場合はフェデレーションサービス）が一時的に利用できないか、プランの処理能力が一時的に上限に達しています。何も書き込まれていないか、フェデレーションサービスの場合は接続レコードのみが書き込まれています。Retry-After 期間の後に再試行してください。 |
errors[].pointer |
errors[].code |
意味 |
|---|---|---|
/resolved_secrets/<NAME> |
secret_missing |
プランはこのシークレットを必要とします。 |
/resolved_secrets/<NAME> |
secret_unused |
プランはこのシークレットを必要としません。 |
/resolved_secrets/<NAME> |
secret_invalid |
値が空、8 KiB より長い、またはテキストではありません。 |
/resolved_secrets/<NAME> |
invalid |
名前が KEENAUTH_… 形式ではありません（A-Z、0-9、_）。 |
/sp_host |
sp_host_required、sp_host_unused、invalid |
プランが OIDC 素材を作成するのにホストが指定されていないか、ホストが不要か、ホストが小文字の DNS 名ではありません。 |
/changes/<i>/spec/oidc/... |
接続の OIDC API と同じ | フェデレーションサービスが、プランの changes のこの位置で素材を拒否しました。 |
/confirm_deletions/<i> |
duplicate、not_a_deletion |
項目が重複しているか、プランに含まれる削除ではありません。 |
/confirm_deletions/<i> |
invalid |
項目が <kind>/<key> 形式ではありません。 |
/resolved_secrets、/confirm_deletions |
too_many |
5,000 件を超えるエントリがあります。 |
/changes/<i>/spec/... |
リソース自身の API と同じ | 環境が、プランの changes のこの位置で変更を拒否しました。 |
例
curl -X POST "https://api.eu.keenauth.com/v1/config-plans/cfgp_01m4qpqtywfs7930tb6kqn5rc5:apply" \
-H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"confirm_deletions": ["connection/legacy"]}'
keenauth config apply cfgp_01m4qpqtywfs7930tb6kqn5rc5 --confirm-deletion connection/legacy
keenauth config apply --secrets-from-env は、プランが必要とする各シークレットを同名の環境変数から読み取り、その値を出力することはありません。