# Crear un cliente de gestión

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

Crea el registro de cliente de gestión de una aplicación de tipo `management`: los permisos de la API de gestión que el cliente puede usar y las redes desde las que puede llamar. El ID del registro es el ID de la aplicación, así que una aplicación tiene como máximo un registro. Solo una clave de API puede llamar a este endpoint.

El cliente se autentica con `private_key_jwt` (RFC 7523). Sus claves públicas no forman parte de este recurso: regístrelas con `POST /v1/applications/{application_id}/credentials` (`type: public_key`). Enviar aquí `jwks_uri` o `public_keys` se rechaza como campo desconocido.

El cliente obtiene un token de acceso del endpoint `/oauth2/token` de su entorno (`client_credentials`, `audience` = el identificador de la API de gestión) y lo envía como `Authorization: Bearer`. El token es válido como máximo 10 minutos. Sus permisos en la API de gestión son los valores de `scope` del token que este registro también enumera; una llamada desde fuera de `allowed_cidrs` falla con `403 ip_not_allowed`. Si el registro o la aplicación se elimina, o la aplicación se suspende, el token se rechaza con `401`. Solo se aceptan tokens de acceso JWT.

## Solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `application_id` | string | sí | Una aplicación de tipo `management` en este entorno (`app_…`). |
| `permissions` | string[] | sí | De 1 a 200 permisos conocidos de la API de gestión con el formato `<resource>:<action>`, por ejemplo `users:read`. Se eliminan los duplicados y la lista se ordena. |
| `allowed_cidrs` | string[] | no | Hasta 20 bloques CIDR, por ejemplo `203.0.113.0/24`. Los bits de host se ponen a cero. Si lo omite, se usa la lista propia de la clave que realiza la llamada. |

Una clave restringida solo puede conceder los permisos que ella misma posee, y una clave con lista de IP permitidas solo puede conceder redes dentro de la suya; en caso contrario, la solicitud falla con `403 permission_escalation`.

## Respuesta

`201 Created`, con una cabecera `ETag` que se envía como `If-Match` para actualizar o eliminar el registro.

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

Cada escritura se registra en el registro de auditoría de gestión con el destino (`management_client` y el ID de la aplicación); los valores de permisos y las redes no se escriben en el registro.

## Errores

| HTTP | code | Cuándo |
|---|---|---|
| 400 | `unknown_field` | El cuerpo contiene un campo que no aparece en la lista anterior, como `jwks_uri` o `public_keys`. |
| 403 | `insufficient_permissions` | La credencial no tiene `management-clients:write`, o no es una clave de API. |
| 403 | `permission_escalation` | La clave que realiza la llamada no puede conceder estos permisos o redes. |
| 404 | `not_found` | No existe esa aplicación en este entorno. |
| 409 | `conflict` | La aplicación ya tiene un registro de cliente de gestión. |
| 422 | `validation_failed` | Falta un campo o no es válido: permiso desconocido, CIDR no válido, `application_id` mal formado, o una aplicación que no es de tipo `management` (puntero `/application_id`). |

## Ejemplo

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