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