Create a management client
POST /v1/management-clients · permission management-clients:write
Creates the management client record of an application of type management: the management API permissions the client may use and the networks it may call from. The record ID is the application ID, so an application has at most one record. Only an API key can call this endpoint.
The client authenticates with private_key_jwt (RFC 7523). Its public keys are not part of this resource: register them with POST /v1/applications/{application_id}/credentials (type: public_key). Sending jwks_uri or public_keys here is rejected as an unknown field.
The client gets an access token from its environment's /oauth2/token endpoint (client_credentials, audience = the management API identifier) and sends it as Authorization: Bearer. The token is valid for at most 10 minutes. Its permissions on the management API are the token's scope values that this record also lists; a call from outside allowed_cidrs fails with 403 ip_not_allowed. If the record or the application is deleted, or the application is suspended, the token is rejected with 401. Only JWT access tokens are accepted.
Request
| Field | Type | Required | Description |
|---|---|---|---|
application_id |
string | yes | An application of type management in this environment (app_…). |
permissions |
string[] | yes | 1-200 known <resource>:<action> management API permissions, for example users:read. Duplicates are removed and the list is sorted. |
allowed_cidrs |
string[] | no | Up to 20 CIDR blocks, for example 203.0.113.0/24. Host bits are cleared. If you leave it out, the calling key's own list is used. |
A restricted key can only grant permissions it holds itself, and a key with an IP allowlist can only grant networks inside its own; otherwise the request fails with 403 permission_escalation.
Response
201 Created, with an ETag header that you send as If-Match to update or delete the record.
{
"application_id": "app_01h455vb4pex5vsknk084sn02q",
"permissions": ["users:read", "users:write"],
"allowed_cidrs": ["203.0.113.0/24"]
}
Every write is recorded in the management audit log with the target (management_client and the application ID); permission values and networks are not written to the log.
Errors
| HTTP | code | When |
|---|---|---|
| 400 | unknown_field |
The body contains a field that is not listed above, such as jwks_uri or public_keys. |
| 403 | insufficient_permissions |
The credential lacks management-clients:write, or it is not an API key. |
| 403 | permission_escalation |
The calling key cannot grant these permissions or networks. |
| 404 | not_found |
There is no such application in this environment. |
| 409 | conflict |
The application already has a management client record. |
| 422 | validation_failed |
A field is missing or invalid: unknown permission, invalid CIDR, malformed application_id, or an application that is not of type management (pointer /application_id). |
Example
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