# 権限を作成

`POST /v1/permissions` · 権限 `apis:write`

API に権限（OAuth スコープ）を追加します。同意画面に表示するテキストも必要に応じて指定できます。`Idempotency-Key` に対応しています。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `api_id` | string | はい | 対象の API（`api_…`）。 |
| `value` | string | はい | スコープの値。`resource:action` 形式（`^[a-z0-9_.-]{1,64}:[a-z0-9_.*-]{1,64}$`）。API 内で一意であり、変更できません。`idp_` プレフィックスは予約されています。 |
| `display_name` | string \| null | いいえ | 同意画面で、スコープの値の代わりに表示される短い名前。128 文字以内。 |
| `description` | string \| null | いいえ | 同意画面で名前の下に表示される詳細説明。1024 文字以内。 |
| `consent_text_i18n` | object \| null | いいえ | 言語タグから同意画面のテキストへの対応。例：`{"en": "Read your orders"}`。30 言語まで、各テキストは 1〜1024 文字、合計 16 KiB まで。 |
| `sensitivity` | string | いいえ | `normal`（既定）または `sensitive`。 |

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

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

## レスポンス

`201 Created`

```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` | リクエストボディに未知のフィールドが含まれています。 |
| 403 | `insufficient_permissions` | 認証情報に `apis:write` がありません。 |
| 403 | `quota_exceeded` | API にすでに 1,000 件の権限があります。 |
| 404 | `not_found` | この環境に該当する API が存在しません。 |
| 409 | `conflict` | 同じ value がこの API にすでに存在するか、対象がシステム API です。 |
| 422 | `validation_failed` | フィールドが欠けているか無効であるか、テキストがプレーンテキストではありません（`errors[].pointer` が該当フィールドを示します。例：`/consent_text_i18n`）。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/permissions \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c1e-perm-create" \
  -d '{"api_id":"api_01h455vb4pex5vsknk084sn02q","value":"read:orders","display_name":"Read orders","consent_text_i18n":{"en":"Read your orders"}}'
```

CLI を使う場合は、`--data` で言語マップを渡します。

```bash
echo '{"consent_text_i18n":{"en":"Read your orders"}}' | keenauth permissions create \
  --api-id api_01h455vb4pex5vsknk084sn02q --value read:orders --display-name "Read orders" --data -
```