# 環境のテーマを更新する

`PATCH /v1/branding` · 権限 `branding:write`

JSON merge patch（`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` | header | はい | 最後に読み取った下書きの `ETag`（一度も書き込まれていない場合は `"0"`）。欠落している場合は `428`、古い場合は `412`。 |
| `theme` | object \| null | いいえ | 部分的な `BrandingTheme`。すべてのフィールドとグループは `null` にできます。 |

## レスポンス

`200 OK` と、環境の下書きおよびその `ETag` を返します。`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}}'
```