# 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[] | 任意。最大 20 個の CIDR ブロック。 |

## レスポンス

`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`、`restricted` で `permissions` がない、`secret` で `permissions` がある、権限または CIDR の形式が不正、`expires_at` が過去、または 730 日を超えて先である、のいずれかです。 |

## 例

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