구성 변경 계획

POST /v1/config-plans · 권한 config:read와 문서에 있는 각 종류의 읽기 권한

구성 문서를 환경의 현재 구성과 비교하고 결과를 계획으로 저장합니다. 아무것도 변경되지 않습니다. 계획은 문서를 적용하면 무엇이 바뀌는지만 보여 줍니다. development에서 staging 또는 production으로 승격하기 전에 검토할 때 사용하세요.

요청

• 문서의 종류는 kinds가 있으면 그것이고(이때 모든 리소스는 나열된 종류여야 함), 없으면 리소스의 종류입니다. 이 종류만 비교하며 다른 종류는 그대로 둡니다.
• 문서에 없는 리소스는 prune이 true가 아니면 삭제되지 않습니다. 단일 종류(environment_settings, identity_settings, branding)는 절대 삭제되지 않습니다.
• 단일 종류에서 문서에 없는 필드는 변경되지 않으며 대상의 현재 값이 유지됩니다. 따라서 필드가 추가되기 전에 내보낸 문서는 그 필드를 초기화하지 않습니다. null을 포함해 명시적으로 지정한 값은 그대로 기록됩니다. 다른 종류에서는 없는 필드가 기본값을 받습니다.
• 문서에는 비밀 값이 있으면 안 됩니다. 비밀 필드에는 secret_ref 자리 표시자나 null만 넣을 수 있으며, 값은 거부되고 응답에 다시 표시되지 않습니다.
• 문서의 warnings는 무시됩니다. 최대 15,000개까지 허용됩니다(내보내기에는 그보다 많이 포함되지 않습니다).
• 권한은 같은 종류를 내보낼 때와 같습니다. prune을 사용하면 삭제되는 리소스를 참조할 수 있는 종류도 읽으므로 그 권한도 필요합니다.

응답

201 Created, Location: /v1/config-plans/{plan_id}와 Cache-Control: no-store 포함.

각 변경에는 kind, key, action(create, update, delete 또는 no_op), object_version(계획 시점 대상 리소스의 버전, create에서는 null), requires_secret, fields, 그리고 create와 update에서는 원하는 spec이 있습니다. fields의 각 항목은 필드 차이입니다. pointer(RFC 6901, 예: /spec/name), op(RFC 6902와 같은 add, remove 또는 replace), before, after. 목록은 전체 값으로 비교합니다.

내보낸 문서를 변경하지 않고 보내면 리소스와 집합형 목록의 순서와 관계없이 모든 리소스가 no_op으로 계획됩니다.

{
  "id": "cfgp_01m4qpqtywfs7930tb6kqn5rc5",
  "status": "planned",
  "prune": false,
  "kinds": ["connection"],
  "expires_at": "2026-10-12T11:00:00Z",
  "summary": {"create": 1, "update": 1, "delete": 0, "no_op": 1},
  "changes": [
    {"kind": "connection", "key": "db", "action": "no_op", "object_version": 5, "requires_secret": false, "fields": []},
    {"kind": "connection", "key": "github", "action": "create", "object_version": null, "requires_secret": true, "fields": [], "spec": {"type": "social", "strategy": "github", "name": "GitHub", "display_name": null, "status": "active", "settings": {}, "client_secret": {"secret_ref": {"source": "env", "name": "KEENAUTH_CONNECTION_GITHUB_CLIENT_SECRET"}}}},
    {"kind": "connection", "key": "google", "action": "update", "object_version": 4, "requires_secret": false, "fields": [{"pointer": "/spec/name", "op": "replace", "before": "Google", "after": "Google Workspace"}], "spec": {"type": "social", "strategy": "google", "name": "Google Workspace", "display_name": null, "status": "active", "settings": {}, "client_secret": {"secret_ref": {"source": "env", "name": "KEENAUTH_CONNECTION_GOOGLE_CLIENT_SECRET"}}}}
  ],
  "warnings": [{"code": "secret_required", "kind": "connection", "key": "github", "pointer": "/spec/client_secret"}]
}

모든 계획은 환경의 관리 로그에 config_plan.created 항목을 기록합니다.

제한

• 속도: 플랜에는 환경별 분당 자체 한도가 있습니다. production에서 Free 20, Startup과 Business 60, Enterprise 120이며 development와 staging에서는 그 10분의 1(최소 2)입니다.
• 환경별 할당량: 적용되지도 만료되지도 않은 플랜은 최대 100개, 삭제될 때까지(만료 7일 후) 저장되는 플랜은 최대 2,000개 및 1 GiB입니다. 다른 환경의 플랜은 계산되지 않습니다.
• 용량: 서버는 큰 플랜을 동시에 제한된 수만 계산하며, 한 환경은 그 용량의 최대 4분의 1만 사용할 수 있습니다.
• 필드 제한은 구성 서비스가 쓰기 시 적용하는 제한입니다. 스키마가 목록과 텍스트를 제한하고(예: redirect_uris 50, allowed_web_origins 20, permissions 1,000), 연결의 settings는 최대 32 KiB, 깊이 8단계, 애플리케이션의 jwks와 각 권한의 consent_text_i18n은 최대 16 KiB입니다.

오류

예제

curl -X POST "https://api.eu.keenauth.com/v1/config-plans" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"document\": $(cat keenauth.json), \"prune\": false}"

keenauth config plan -f keenauth.yaml