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가 추가됩니다.

{
  "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`인 경우입니다.

예제

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"}'