# Créer un client de gestion

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

Crée l'enregistrement de client de gestion d'une application de type `management` : les autorisations de l'API de gestion que le client peut utiliser et les réseaux depuis lesquels il peut appeler. L'identifiant de l'enregistrement est l'identifiant de l'application ; une application n'a donc qu'un seul enregistrement au plus. Seule une clé d'API peut appeler ce point de terminaison.

Le client s'authentifie avec `private_key_jwt` (RFC 7523). Ses clés publiques ne font pas partie de cette ressource : enregistrez-les avec `POST /v1/applications/{application_id}/credentials` (`type: public_key`). L'envoi de `jwks_uri` ou de `public_keys` ici est rejeté comme champ inconnu.

Le client obtient un jeton d'accès auprès du point de terminaison `/oauth2/token` de son environnement (`client_credentials`, `audience` = l'identifiant de l'API de gestion) et l'envoie dans `Authorization: Bearer`. Le jeton est valide au maximum 10 minutes. Ses autorisations sur l'API de gestion sont les valeurs `scope` du jeton que cet enregistrement liste également ; un appel depuis l'extérieur de `allowed_cidrs` échoue avec `403 ip_not_allowed`. Si l'enregistrement ou l'application est supprimé, ou si l'application est suspendue, le jeton est rejeté avec `401`. Seuls les jetons d'accès JWT sont acceptés.

## Requête

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `application_id` | chaîne | oui | Une application de type `management` dans cet environnement (`app_…`). |
| `permissions` | chaîne[] | oui | 1 à 200 autorisations connues de l'API de gestion au format `<resource>:<action>`, par exemple `users:read`. Les doublons sont supprimés et la liste est triée. |
| `allowed_cidrs` | chaîne[] | non | Jusqu'à 20 blocs CIDR, par exemple `203.0.113.0/24`. Les bits de l'hôte sont mis à zéro. Si vous l'omettez, la liste propre à la clé appelante est utilisée. |

Une clé restreinte ne peut accorder que les autorisations qu'elle détient elle-même, et une clé avec une liste d'IP autorisées ne peut accorder que des réseaux inclus dans la sienne ; sinon, la requête échoue avec `403 permission_escalation`.

## Réponse

`201 Created`, avec un en-tête `ETag` que vous envoyez en `If-Match` pour modifier ou supprimer l'enregistrement.

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

Chaque écriture est consignée dans le journal d'audit de gestion avec sa cible (`management_client` et l'identifiant de l'application) ; les valeurs d'autorisation et les réseaux ne sont pas écrits dans le journal.

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 400 | `unknown_field` | Le corps contient un champ non listé ci-dessus, comme `jwks_uri` ou `public_keys`. |
| 403 | `insufficient_permissions` | L'identifiant ne possède pas `management-clients:write`, ou ce n'est pas une clé d'API. |
| 403 | `permission_escalation` | La clé appelante ne peut pas accorder ces autorisations ou ces réseaux. |
| 404 | `not_found` | Il n'existe pas d'application de ce type dans cet environnement. |
| 409 | `conflict` | L'application possède déjà un enregistrement de client de gestion. |
| 422 | `validation_failed` | Un champ est absent ou invalide : autorisation inconnue, CIDR invalide, `application_id` mal formé, ou application qui n'est pas de type `management` (pointeur `/application_id`). |

## Exemple

```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`