# 권한 생성

`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`은 상세 설명 줄로 표시됩니다. 세 가지 모두 일반 텍스트입니다. 제어 문자(줄바꿈과 탭 포함), 줄 및 단락 구분자, 양방향 임베딩, 재정의 및 격리 문자(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` | 이 API에 이미 같은 값이 있거나, 이 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 -
```