# Crea un client di gestione

`POST /v1/management-clients` · permesso `management-clients:write`

Crea il record del client di gestione di un'applicazione di tipo `management`: i permessi dell'API di gestione che il client può usare e le reti da cui può effettuare chiamate. L'ID del record è l'ID dell'applicazione, quindi un'applicazione ha al massimo un record. Solo una chiave API può chiamare questo endpoint.

Il client si autentica con `private_key_jwt` (RFC 7523). Le sue chiavi pubbliche non fanno parte di questa risorsa: registrale con `POST /v1/applications/{application_id}/credentials` (`type: public_key`). Inviare qui `jwks_uri` o `public_keys` viene rifiutato come campo sconosciuto.

Il client ottiene un access token dall'endpoint `/oauth2/token` del suo ambiente (`client_credentials`, `audience` = l'identificatore dell'API di gestione) e lo invia come `Authorization: Bearer`. Il token è valido al massimo 10 minuti. I suoi permessi sull'API di gestione sono i valori di `scope` del token che anche questo record elenca; una chiamata da fuori da `allowed_cidrs` fallisce con `403 ip_not_allowed`. Se il record o l'applicazione viene eliminato, oppure l'applicazione viene sospesa, il token viene rifiutato con `401`. Sono accettati solo access token JWT.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `application_id` | string | sì | Un'applicazione di tipo `management` in questo ambiente (`app_…`). |
| `permissions` | string[] | sì | Da 1 a 200 permessi noti dell'API di gestione nel formato `<resource>:<action>`, ad esempio `users:read`. I duplicati vengono rimossi e l'elenco viene ordinato. |
| `allowed_cidrs` | string[] | no | Fino a 20 blocchi CIDR, ad esempio `203.0.113.0/24`. I bit dell'host vengono azzerati. Se lo ometti, viene usata la lista della chiave che effettua la chiamata. |

Una chiave con restrizioni può concedere solo i permessi che possiede a sua volta, e una chiave con lista di IP consentiti può concedere solo reti contenute nella propria; altrimenti la richiesta fallisce con `403 permission_escalation`.

## Risposta

`201 Created`, con un'intestazione `ETag` da inviare come `If-Match` per aggiornare o eliminare il record.

```json
{
  "application_id": "app_01h455vb4pex5vsknk084sn02q",
  "permissions": ["users:read", "users:write"],
  "allowed_cidrs": ["203.0.113.0/24"]
}
```

Ogni scrittura viene registrata nel log di audit di gestione con il destinatario (`management_client` e l'ID dell'applicazione); i valori dei permessi e le reti non vengono scritti nel log.

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `unknown_field` | Il corpo contiene un campo non elencato sopra, come `jwks_uri` o `public_keys`. |
| 403 | `insufficient_permissions` | La credenziale non ha `management-clients:write`, oppure non è una chiave API. |
| 403 | `permission_escalation` | La chiave che effettua la chiamata non può concedere questi permessi o queste reti. |
| 404 | `not_found` | In questo ambiente non esiste tale applicazione. |
| 409 | `conflict` | L'applicazione ha già un record di client di gestione. |
| 422 | `validation_failed` | Un campo manca o non è valido: permesso sconosciuto, CIDR non valido, `application_id` malformato, oppure un'applicazione non di tipo `management` (puntatore `/application_id`). |

## Esempio

```bash
curl -X POST https://api.eu.keenauth.com/v1/management-clients \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"application_id":"app_01h455vb4pex5vsknk084sn02q","permissions":["users:read","users:write"],"allowed_cidrs":["203.0.113.0/24"]}'
```

CLI: `keenauth management-clients create --application-id app_01h455vb4pex5vsknk084sn02q --permissions users:read,users:write --allowed-cidrs 203.0.113.0/24`