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