# ブランディング下書きを公開

`POST /v1/branding:publish` · 権限 `branding:write`

すべての下書き (環境、アプリケーション、組織、テキスト) のスナップショットを作成し、ホスト型ページの公開バージョンにします。公開前に各スコープの有効なテーマを検査します: 必須トークン、値の範囲、各カラーペアの WCAG コントラスト。問題が 1 つでもあれば公開全体が `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 | コード | 概要 |
|---|---|---|
| 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)"
```