# 브랜딩 초안 게시

`POST /v1/branding:publish` · 권한 `branding:write`

모든 초안(환경, 애플리케이션, 조직, 텍스트)의 스냅샷을 만들어 호스팅 페이지의 라이브 버전으로 지정합니다. 게시 전에 모든 범위의 유효 테마를 검사합니다: 필수 토큰, 값 범위, 각 색상 쌍의 WCAG 대비. 문제가 하나라도 있으면 전체 게시가 `422 branding_validation_failed`로 거부되며, `issues[]` 목록이 변경해야 할 모든 토큰을 알려 줍니다(대비의 경우 측정된 `ratio`, `threshold`, 기준을 충족하는 가장 가까운 `suggestion` 포함). 최근 50개 버전이 보관됩니다. `Idempotency-Key`는 선택 사항입니다.

초안에 사용자 지정 CSS가 있으면 게시 전에 호스팅 화면에 렌더링하여 검사합니다(최대 25초가 걸릴 수 있는 렌더링 검사이므로 클라이언트 시간 제한을 최소 30초로 설정하세요). 보호된 요소를 깨뜨리거나, CSS가 없으면 페이지에 없을 접근성 위반을 추가하는 CSS는 `422 branding_validation_failed`와 `render_violations[]` 목록으로 게시를 거부합니다. 검사 중 초안이 변경되면 아무것도 게시되지 않고 `409 conflict`가 반환됩니다. 다시 게시하세요.

## 요청

이 작업은 경로, 쿼리, 본문 필드를 받지 않습니다. 환경은 자격 증명에서 결정됩니다.

## 응답

`200 OK`와 새 버전의 메타데이터 (스냅샷 자체는 반환되지 않습니다).

```json
{
  "version": 4,
  "snapshot_sha256": "3f1c…",
  "source": "publish",
  "rolled_back_from": null,
  "actor_type": "api_key",
  "actor_id": "key_01jb…",
  "published_at": "2026-10-05T09:31:00Z"
}
```

```json
{
  "type": "https://docs.keenauth.com/problems/branding_validation_failed",
  "status": 422,
  "code": "branding_validation_failed",
  "issues": [
    {"scope_type": "environment", "code": "brand_contrast_insufficient", "field": "light.color.primary_contrast",
     "variant": "light", "pair": "primary_contrast_on_primary", "ratio": 2.1, "threshold": 4.5, "suggestion": "#ffffff"}
  ]
}
```

렌더링 검사 거부는 모든 발견 사항을 나열합니다: `screen`(예: `password`), `locale`(`en`, `ar` 또는 `ja`), `width`(CSS 픽셀 단위의 뷰포트 너비, 320 또는 1280), `rule`(`protected_no_area`, `protected_not_visible`, `protected_transparent`, `protected_covered`, `protected_contrast` 또는 `color-contrast`와 같은 axe-core 규칙 ID), `target`(보호된 요소의 이름 또는 axe-core CSS 선택자). CSS 값은 응답에 포함되지 않습니다. 발견 사항은 최대 100개가 반환되며, 더 많은 경우 `render_violations_truncated`가 `true`입니다.

```json
{
  "type": "https://docs.keenauth.com/errors/branding_validation_failed",
  "status": 422,
  "code": "branding_validation_failed",
  "render_violations": [
    {"screen": "recovery", "locale": "ar", "width": 320, "rule": "protected_covered", "target": "recovery_codes_hint"}
  ],
  "render_violations_truncated": false
}
```

## 오류

| HTTP | code | 조건 |
|---|---|---|
| 403 | `plan_feature_unavailable` | 초안에 사용자 지정 CSS 또는 페이지 템플릿이 있으나 플랜에 포함되어 있지 않습니다(`feature`가 어느 것인지 알려 줍니다). |
| 422 | `branding_validation_failed` | 초안을 게시할 수 없습니다. `issues[]`를 확인하세요. 초안의 사용자 정의 CSS는 게시 시 다시 정제되며, 실패하면 위반 사항이 `violations[]` 확장에 있습니다(`PUT /v1/branding/css` 참조). 사용자 정의 CSS가 렌더링 검사에 실패하면 발견 사항은 `render_violations[]`와 `render_violations_truncated`에 있습니다. |
| 409 | `conflict` | 사용자 정의 CSS를 검사하는 동안 초안이 변경되었으며, 아무것도 게시되지 않았습니다. 다시 게시하세요. |
| 401 | `unauthenticated` | 자격 증명이 없거나 유효하지 않거나 폐기되었습니다. |
| 403 | `insufficient_permissions` | 자격 증명에 필요한 권한이 없습니다. |
| 429 | `rate_limited` | 속도 제한을 초과했습니다. `Retry-After` 기간 후에 다시 시도하세요. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다(사용자 정의 CSS가 있는 초안의 렌더링 검사 포함). `Retry-After` 기간 후에 다시 시도하세요. |

## 예제

```bash
curl -X POST https://api.eu.keenauth.com/v1/branding:publish \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```