# 権限を更新する

`PATCH /v1/permissions/{permission_id}` · 権限 `apis:write`

JSONマージパッチ（RFC 7396、`application/merge-patch+json`）で権限を更新します。送信したフィールドのみが変更され、それ以外は維持されます。権限にはバージョンがないため、`If-Match` はありません。

## リクエスト

| パラメータ | 入力 | 説明 |
|---|---|---|
| `permission_id` | path | 権限ID（`perm_…`）。 |

本文: 以下のフィールドのいずれか（すべて省略可能、少なくとも1つ必要）。

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `value` | 文字列 | いいえ | 現在の値と同じ場合にのみ受け付けられます。値は変更されません。 |
| `display_name` | 文字列 \| null | いいえ | スコープの値の代わりに同意画面に表示される短い名前。最大128文字。 |
| `description` | 文字列 \| null | いいえ | 同意画面で名前の下に表示される詳細行。最大1024文字。 |
| `consent_text_i18n` | オブジェクト \| null | いいえ | 言語タグ → 同意画面のテキスト（例: `{"en": "Read your orders"}`）。最大30言語、各テキストは1〜1024文字、合計16 KiB。 |
| `sensitivity` | 文字列 | いいえ | `normal`（既定値）または `sensitive`。 |

`display_name`、`description`、`consent_text_i18n` は `null` を指定して消去できます。`sensitivity` は消去できません。`consent_text_i18n` は全体が置き換えられます。省略した言語は削除されるため、残したい言語はすべて送信してください。

### 同意画面のテキスト

ホストされる同意画面は、要求された各スコープを次のように表示します。ページの言語に対応する `consent_text_i18n` の項目（完全一致するタグ、なければその基本サブタグ）、なければ `display_name`、それもなければスコープの `value` です。`description` は詳細行として表示されます。3つの値はすべてプレーンテキストです。制御文字（改行とタブを含む）、行・段落の区切り文字、双方向の埋め込み・上書き・分離文字（U+202A〜U+202E、U+2066〜U+2069）は `422` で拒否されます。前後の空白は除去され、除去後に空になったテキストは `null` として保存されます。HTMLは解釈されず、同意画面でエスケープされます。

## レスポンス

`200 OK`

```json
{
  "id": "perm_01h455vb4pex5vsknk084sn02s",
  "api_id": "api_01h455vb4pex5vsknk084sn02q",
  "value": "read:orders",
  "display_name": "Read orders",
  "description": "See your past orders and their status",
  "consent_text_i18n": {
    "en": "Read your orders",
    "tr": "Siparişlerinizi okuyun"
  },
  "sensitivity": "normal"
}
```

## エラー

| HTTP | code | 情況 |
|---|---|---|
| 400 | `unknown_field` | パッチに `api_id` または未知のフィールドがあります。 |
| 404 | `not_found` | この環境にそのような権限はありません。 |
| 409 | `conflict` | 権限はシステムAPIに属しています。 |
| 415 | `unsupported_media_type` | コンテンツタイプが `application/merge-patch+json` ではありません。 |
| 422 | `validation_failed` | パッチが空、値が無効またはプレーンテキストではない、`sensitivity` が `null`、または `value` が異なります（`immutable`）。 |

## 例

```bash
curl -X PATCH https://api.eu.keenauth.com/v1/permissions/perm_01h455vb4pex5vsknk084sn02s \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"description":"See your past orders and their status","consent_text_i18n":{"en":"Read your orders","tr":"Siparişlerinizi okuyun"}}'
```