# Crea una chiave API

`POST /v1/api-keys` · autorizzazione `api-keys:write` · `Idempotency-Key` obbligatoria

Crea una chiave API di gestione per l'ambiente. Una chiave `secret` accede a tutta la API di gestione; una chiave `restricted` ha solo le autorizzazioni elencate (`<resource>:<action>`).

- **Chiave in chiaro.** La risposta contiene `key` una sola volta (`idp_sk_live_…`, `idp_sk_test_…`, `idp_rk_live_…` o `idp_rk_test_…`). Non può essere recuperata di nuovo; salvala subito. La risposta ha `Cache-Control: no-store`.
- **Nessuna escalation.** Una chiave non può creare una chiave con autorizzazioni superiori alle proprie, e una chiave `restricted` non può creare una chiave `secret`. La nuova chiave non può scadere dopo la chiave chiamante, e una chiave chiamante con `allowed_cidrs` può creare solo chiavi limitate a reti interne alle proprie; se `allowed_cidrs` è omesso, la nuova chiave riceve la lista della chiave chiamante (`permission_escalation`).
- **Limiti.** Al massimo 50 chiavi attive per ambiente, al massimo 20 blocchi CIDR per chiave, scadenza al massimo 730 giorni nel futuro. Una chiave con `allowed_cidrs` è accettata solo da quelle reti.
- **Replay idempotente.** Ripetere la richiesta con la stessa `Idempotency-Key` riproduce la risposta memorizzata senza la chiave: il corpo ha `secret_redacted: true` e nessun `key`. Crea una nuova chiave se quella precedente è stata persa.

## Richiesta

Corpo:

| Campo | Tipo | Descrizione |
|---|---|---|
| `name` | string | Obbligatorio. Da 1 a 100 caratteri. |
| `type` | string | Obbligatorio. `secret` o `restricted`. |
| `permissions` | string[] | Obbligatorio e non vuoto per `restricted` (al massimo 200); assente o vuoto per `secret`. Non può superare le autorizzazioni del chiamante. |
| `expires_at` | string (date-time) | Obbligatorio, nel futuro, al massimo 730 giorni avanti. |
| `allowed_cidrs` | string[] | Facoltativo, al massimo 20 blocchi CIDR. |

## Risposta

`201 Created` con `Cache-Control: no-store`. L'oggetto chiave come nella risposta della lista, più `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>"
}
```

## Errori

| HTTP | `code` | Quando |
|---|---|---|
| 401 | `unauthenticated` | La chiave manca, non è valida o è revocata. |
| 403 | `insufficient_permissions` | La chiave non ha l'autorizzazione richiesta. |
| 403 | `permission_escalation` | La richiesta darebbe a una chiave più autorizzazioni, un intervallo di rete più ampio o una scadenza più lontana di quelle della chiave chiamante; una chiave `restricted` tenta di creare, ruotare o revocare oltre le proprie autorizzazioni; oppure un'altra chiave tenta di ruotare o revocare una chiave creata dalla dashboard. |
| 409 | `api_key_limit_reached` | L'ambiente ha già il massimo di 50 chiavi attive. |
| 422 | `validation_failed` | Il corpo non è valido: `name` mancante o troppo lungo, `type` sconosciuto, `restricted` senza `permissions`, `secret` con `permissions`, autorizzazione o CIDR malformati, `expires_at` nel passato o oltre 730 giorni. |

## Esempio

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