Management-Client erstellen

POST /v1/management-clients · Berechtigung management-clients:write

Erstellt den Management-Client-Datensatz einer Anwendung vom Typ management: die Berechtigungen der Management-API, die der Client nutzen darf, und die Netzwerke, aus denen er aufrufen darf. Die Datensatz-ID ist die Anwendungs-ID; eine Anwendung hat daher höchstens einen Datensatz. Nur ein API-Schlüssel kann diesen Endpunkt aufrufen.

Der Client authentifiziert sich mit private_key_jwt (RFC 7523). Seine öffentlichen Schlüssel sind nicht Teil dieser Ressource: Registrieren Sie sie über POST /v1/applications/{application_id}/credentials (type: public_key). Das Senden von jwks_uri oder public_keys wird hier als unbekanntes Feld abgelehnt.

Der Client erhält ein Zugriffstoken vom Endpunkt /oauth2/token seiner Umgebung (client_credentials, audience = die Kennung der Management-API) und sendet es als Authorization: Bearer. Das Token ist höchstens 10 Minuten gültig. Seine Berechtigungen auf der Management-API sind die scope-Werte des Tokens, die auch dieser Datensatz auflistet; ein Aufruf von außerhalb von allowed_cidrs schlägt mit 403 ip_not_allowed fehl. Wird der Datensatz oder die Anwendung gelöscht oder die Anwendung gesperrt, wird das Token mit 401 abgelehnt. Es werden nur JWT-Zugriffstoken akzeptiert.

Anfrage

Feld Typ Erforderlich Beschreibung
application_id String ja Eine Anwendung vom Typ management in dieser Umgebung (app_…).
permissions String[] ja 1–200 bekannte Management-API-Berechtigungen im Format <resource>:<action>, zum Beispiel users:read. Doppelte Einträge werden entfernt und die Liste wird sortiert.
allowed_cidrs String[] nein Bis zu 20 CIDR-Blöcke, zum Beispiel 203.0.113.0/24. Host-Bits werden auf null gesetzt. Wenn Sie das Feld weglassen, wird die eigene Liste des aufrufenden Schlüssels verwendet.

Ein eingeschränkter Schlüssel kann nur Berechtigungen vergeben, die er selbst besitzt, und ein Schlüssel mit IP-Allowlist kann nur Netzwerke innerhalb seiner eigenen vergeben; andernfalls schlägt die Anfrage mit 403 permission_escalation fehl.

Antwort

201 Created, mit einem ETag-Header, den Sie als If-Match senden, um den Datensatz zu aktualisieren oder zu löschen.

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

Jeder Schreibvorgang wird im Management-Auditprotokoll mit dem Ziel (management_client und der Anwendungs-ID) erfasst; Berechtigungswerte und Netzwerke werden nicht protokolliert.

Fehler

HTTP code Wann
400 unknown_field Der Body enthält ein Feld, das oben nicht aufgeführt ist, etwa jwks_uri oder public_keys.
403 insufficient_permissions Der Berechtigungsnachweis hat nicht management-clients:write, oder es ist kein API-Schlüssel.
403 permission_escalation Der aufrufende Schlüssel darf diese Berechtigungen oder Netzwerke nicht vergeben.
404 not_found Es gibt keine solche Anwendung in dieser Umgebung.
409 conflict Die Anwendung hat bereits einen Management-Client-Datensatz.
422 validation_failed Ein Feld fehlt oder ist ungültig: unbekannte Berechtigung, ungültiger CIDR, fehlerhafte application_id oder eine Anwendung, die nicht vom Typ management ist (Pointer /application_id).

Beispiel

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