# API 키 생성

`POST /v1/api-keys` · 권한 `api-keys:write` · 필수 `Idempotency-Key`

환경에 대한 관리 API 키를 생성합니다. `secret` 키는 전체 관리 API에 접근할 수 있으며, `restricted` 키는 나열된 권한(`<resource>:<action>`)만 가집니다.

- **원본 키.** 응답에는 `key`가 한 번만 포함됩니다(`idp_sk_live_…`, `idp_sk_test_…`, `idp_rk_live_…` 또는 `idp_rk_test_…`). 다시 조회할 수 없으므로 즉시 안전하게 저장하십시오. 응답에는 `Cache-Control: no-store`가 포함됩니다.
- **권한 상승 금지.** 키는 자신의 권한을 초과하는 권한을 가진 키를 만들 수 없으며, `restricted` 키는 `secret` 키를 만들 수 없습니다. 새 키의 만료일은 호출한 키보다 늦을 수 없고, `allowed_cidrs`가 설정된 호출 키는 자신의 네트워크 범위 안에서만 제한된 키를 만들 수 있습니다. `allowed_cidrs`를 생략하면 새 키는 호출 키의 목록을 그대로 받습니다(`permission_escalation`).
- **제한.** 환경당 활성 키는 최대 50개, 키당 CIDR 블록은 최대 20개이며, 만료일은 현재로부터 최대 730일 이내여야 합니다. `allowed_cidrs`가 설정된 키는 해당 네트워크에서만 허용됩니다.
- **멱등 재생.** 같은 `Idempotency-Key`로 요청을 반복하면 저장된 응답이 키 없이 재생됩니다. 본문에는 `secret_redacted: true`가 포함되고 `key`는 없습니다. 키를 분실한 경우 새 키를 생성하십시오.

## 요청

본문:

| 필드 | 타입 | 설명 |
|---|---|---|
| `name` | string | 필수입니다. 1~100자입니다. |
| `type` | string | 필수입니다. `secret` 또는 `restricted`입니다. |
| `permissions` | string[] | `restricted`에는 필수이며 비어 있으면 안 됩니다(최대 200개). `secret`에는 생략하거나 비워 둡니다. 호출자의 권한을 초과할 수 없습니다. |
| `expires_at` | string (date-time) | 필수입니다. 미래 시점이어야 하며 현재로부터 최대 730일 이내여야 합니다. |
| `allowed_cidrs` | string[] | 선택 사항입니다. CIDR 블록은 최대 20개입니다. |

## 응답

`201 Created`와 `Cache-Control: no-store`입니다. 목록 응답과 같은 키 객체에 `key`가 추가됩니다.

```json
{
  "id": "key_0000000000000000000000001z",
  "name": "ci",
  "type": "restricted",
  "permissions": ["users:read"],
  "allowed_cidrs": [],
  "last4": "xxxx",
  "created_by": "key_…",
  "created_at": "2026-10-01T10:00:00Z",
  "expires_at": "2027-10-01T10:00:00Z",
  "last_used_at": null,
  "last_used_ip": null,
  "rotated_from": null,
  "revoked_at": null,
  "revoke_reason": null,
  "key": "<shown once>"
}
```

## 오류

| HTTP | `code` | 발생 시점 |
|---|---|---|
| 401 | `unauthenticated` | 키가 없거나 잘못되었거나 취소된 경우입니다. |
| 403 | `insufficient_permissions` | 키에 필요한 권한이 없는 경우입니다. |
| 403 | `permission_escalation` | 요청이 호출 키보다 많은 권한, 더 넓은 네트워크 범위 또는 더 늦은 만료일을 가진 키를 만들려는 경우, `restricted` 키가 자신의 권한을 넘어 키를 생성, 교체 또는 취소하려는 경우, 또는 다른 키가 대시보드에서 만든 키를 교체 또는 취소하려는 경우입니다. |
| 409 | `api_key_limit_reached` | 환경에 이미 활성 키가 최대 개수인 50개 있는 경우입니다. |
| 422 | `validation_failed` | 본문이 잘못된 경우입니다. `name`이 없거나 너무 긴 경우, 알 수 없는 `type`, `permissions` 없이 `restricted`를 보낸 경우, `permissions`를 포함한 `secret`, 형식이 잘못된 권한 또는 CIDR, 과거이거나 현재로부터 730일을 초과하는 `expires_at`인 경우입니다. |

## 예제

```bash
curl -X POST https://api.eu.keenauth.com/v1/api-keys \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci","type":"restricted","permissions":["users:read"],"expires_at":"2027-10-01T10:00:00Z"}'
```