DuoKey Cockpit — API-Überblick
Alles, was Sie zum Aufruf der Cockpit-API benötigen: Basis-URLs, Authentifizierung, Mandantenfähigkeit, Berechtigungen, Konventionen und Fehler.
Zwei Oberflächen
Das Cockpit stellt zwei Arten von HTTP-Oberflächen bereit:
| Oberfläche | Basispfad | Wer sie aufruft |
|---|---|---|
| Management-API | /api/… | Ihre Integrationen und die Cockpit-Konsole — authentifiziert mit einem Bearer-Token |
| Öffentliche Protokollendpunkte | Root-Pfade wie /dke/…, /ocsp/…, /scep/…, .well-known/est/… | Standardclients, die ein öffentliches Protokoll sprechen (Microsoft 365, ACME-/EST-/SCEP-/CMP-Clients, OCSP-Responder) |
Die Basis-URL ist Ihr Cockpit-Host, zum Beispiel https://cockpit.example.com. Alle folgenden Beispiele verwenden Pfade relativ zu diesem Host.
Authentifizierung
Management-API-Aufrufe tragen ein Bearer-Token im Authorization-Header:
Authorization: Bearer <access-token>
Siehe Authentifizierung, um zu erfahren, wie ein Token beschafft wird und wie Sitzungen funktionieren. Öffentliche Protokollendpunkte verwenden die im jeweiligen Standard definierte Authentifizierung (zum Beispiel ein Azure-AD-Token für DKE-Entschlüsselung oder ACME-Kontoschlüssel).
Mandantenfähigkeit
Jede Anfrage läuft im Sicherheitskontext des im Token kodierten Mandanten — Sie übergeben nie explizit eine Mandanten-ID und sehen und ändern nur die Daten Ihres eigenen Mandanten. Einige administrative Endpunkte sind hostbezogen (mandantenübergreifend) und erfordern ein Host-Token; diese sind auf der Seite Plattformadministration gekennzeichnet.
Berechtigungen
Aktionen werden durch rollenbasierte Berechtigungen gesteuert. Ein Aufrufer muss die von einer Route geforderte Berechtigung besitzen (zum Beispiel eine Berechtigung zur Zertifikatsausstellung, um ein Zertifikat auszustellen). Berechtigungsnamen sind nach Bereich gruppiert (Plattformoperationen, PKI, Hostadministration usw.) und werden pro Endpunkt auf jeder API-Seite aufgeführt.
Konventionen
| Aspekt | Konvention |
|---|---|
| Format | JSON-Anfrage- und Antwortkörper; UTF-8 |
| Bezeichner | Ressourcen-IDs sind UUIDs |
| Methoden | Standard-REST: GET (lesen), POST (erstellen/Aktion), PUT/PATCH (aktualisieren), DELETE (entfernen) |
| Zeitstempel | ISO 8601 (UTC) |
| Auth-Header | Authorization: Bearer <token> |
Fehlermodell
Fehler liefern einen Nicht-2xx-HTTP-Status mit einem JSON-Körper, der das Problem beschreibt. Häufige Statuscodes:
| Status | Bedeutung |
|---|---|
| 400 Bad Request | Fehlerhafte Anfrage oder fehlgeschlagene Validierung |
| 401 Unauthorized | Fehlendes oder ungültiges Token |
| 403 Forbidden | Authentifiziert, aber ohne die erforderliche Berechtigung (oder Funktion für die Edition nicht aktiviert) |
| 404 Not Found | Keine solche Ressource in Ihrem Mandanten |
| 409 Conflict | Statuskonflikt (z. B. ein bereits verwendeter Name) |
| 429 Too Many Requests | Ratenlimit überschritten |
API-Abschnitte
Authentifizierung
Ein Token beschaffen und Sitzungen verstehen
Vaults & Keys API
Vaults und Schlüsselmaterial verwalten
Administration API
Benutzer, Rollen, Organisationseinheiten, Identitätsanbieter, Zugriffsrichtlinien
Platform Administration API
Hostbezogen: Mandanten, Hosteinstellungen, Editionen, Funktionen
DKE API
DKE-Dienstverwaltung und das öffentliche GetKey-/Decrypt-Protokoll
PKI API
CAs, Zertifikate, CRL/OCSP, Aussteller, Enrollment-Protokolle, Deployment