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.

{
  "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

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