# 환경 테마 업데이트

`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`는 [브랜딩 자산 업로드](/docs/api/management/branding/upload-asset)로 업로드한 해당 종류의 이미지를 가리켜야 하며, 그렇지 않으면 해당 필드가 `asset_not_found`와 함께 실패합니다. 대비는 게시 시 검사합니다.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `If-Match` | 헤더 | 예 | 마지막으로 읽은 초안의 `ETag`입니다(한 번도 기록하지 않았다면 `"0"`). 누락 시 `428`, 오래된 값이면 `412`를 반환합니다. |
| `theme` | object \| null | 아니요 | 부분 `BrandingTheme`입니다. 모든 필드와 그룹은 `null`일 수 있습니다. |

## 응답

환경 초안과 해당 `ETag`를 담은 `200 OK`를 반환합니다. `theme`에는 설정된 토큰만 포함되며, 설정되지 않은 토큰은 플랫폼 기본값을 상속합니다.

```json
{
  "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` 기간이 지난 후 다시 시도하십시오. |

## 예시

```bash
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}}'
```