환경 테마 업데이트
PATCH /v1/branding · 권한 branding:write
JSON 병합 패치(application/merge-patch+json, RFC 7396)로 환경 테마 초안을 변경합니다. 값을 null로 설정한 토큰(또는 "light": null과 같은 그룹 전체)은 지워지며 다시 상속됩니다. "theme": null을 지정하면 모든 토큰이 지워집니다. 변경된 토큰만 기록되며, 변경 사항이 없는 패치는 버전을 유지합니다. 값은 기록 시 검사합니다. 색상은 #rgb 또는 #rrggbb 형식이어야 하고, font.size_base는 14~18, radius.card는 0~24, radius.control은 0~16, logo_height는 24~80이어야 합니다. logo, favicon, background_image는 브랜딩 자산 업로드로 업로드한 해당 종류의 이미지를 가리켜야 하며, 그렇지 않으면 해당 필드가 asset_not_found와 함께 실패합니다. 대비는 게시 시 검사합니다.
요청
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
If-Match |
헤더 | 예 | 마지막으로 읽은 초안의 ETag입니다(한 번도 기록하지 않았다면 "0"). 누락 시 428, 오래된 값이면 412를 반환합니다. |
theme |
object | null | 아니요 | 부분 BrandingTheme입니다. 모든 필드와 그룹은 null일 수 있습니다. |
응답
환경 초안과 해당 ETag를 담은 200 OK를 반환합니다. theme에는 설정된 토큰만 포함되며, 설정되지 않은 토큰은 플랫폼 기본값을 상속합니다.
{
"theme": {"mode": "light", "light": {"color": {"primary": "#0a3d91"}}, "logo_height": 40},
"css": null,
"page_template": null,
"updated_at": "2026-10-05T09:30:00.123456Z"
}
오류
| HTTP | code | 발생 시점 |
|---|---|---|
| 400 | unknown_field |
본문에 알 수 없는 필드가 있거나 JSON 객체가 아닙니다. |
| 412 | precondition_failed |
If-Match가 초안의 현재 버전과 일치하지 않습니다. |
| 415 | unsupported_media_type |
콘텐츠 유형이 application/merge-patch+json이 아닙니다. |
| 422 | validation_failed |
토큰 값이 유효하지 않습니다(invalid_value, out_of_range, unknown_token). pointer에 토큰이 표시되며, 예를 들면 /theme/light/color/primary입니다. |
| 428 | precondition_required |
If-Match 헤더가 없습니다. |
| 401 | unauthenticated |
자격 증명이 없거나 유효하지 않거나 취소되었습니다. |
| 403 | insufficient_permissions |
자격 증명에 필요한 권한이 없습니다. |
| 429 | rate_limited |
요청 한도를 초과했습니다. Retry-After 기간이 지난 후 다시 시도하십시오. |
| 503 | service_unavailable |
종속 서비스를 일시적으로 사용할 수 없습니다. Retry-After 기간이 지난 후 다시 시도하십시오. |
예시
curl -X PATCH https://api.eu.keenauth.com/v1/branding \
-H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
-H "Content-Type: application/merge-patch+json" \
-H 'If-Match: "3"' \
-d '{"theme":{"light":{"color":{"primary":"#0a3d91"}},"radius":null}}'