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