Vaults & Keys API
Vault-Backends registrieren, mit Apps verknüpfen und das darin gehaltene Schlüsselmaterial verwalten.
Überblick
Jede Route auf dieser Seite befindet sich unter der authentifizierten Management-API unter /api/…. Jede Anfrage trägt ein Bearer-Token:
Authorization: Bearer <access-token>
Anfragen laufen im Sicherheitskontext des im Token kodierten Mandanten — Sie übergeben nie eine Mandanten-ID und sehen oder ändern ausschließlich die Vaults und Schlüssel Ihres eigenen Mandanten. Vault- und Schlüsselaktionen werden zusätzlich durch Vault-Berechtigungen gesteuert: Ein Aufrufer muss die von einer Route geforderte Berechtigung besitzen (zum Beispiel um einen Vault zu registrieren, dessen Schlüssel zu synchronisieren oder eine kryptografische Operation mit einem Schlüssel durchzuführen).
Siehe den API-Überblick für Basis-URLs, Mandantenfähigkeit und das Fehlermodell sowie Authentifizierung, um zu erfahren, wie ein Token beschafft wird.
Vault-Verwaltung
Ein Vault ist ein gespeicherter, mandantenbezogener Datensatz, der eine Backend-Instanz beschreibt (Software, MPC, HSM oder Cloud-KMS). Diese Routen registrieren Vaults, prüfen die Backend-Gesundheit und -Leistung und ermitteln oder importieren die von einem Backend bereits gehaltenen Schlüssel.
| Methode + Pfad | Zweck |
|---|---|
GET · POST /api/vaults | Vaults auflisten · neuen Vault registrieren |
GET · PUT · DELETE /api/vaults/{id} | Einen einzelnen Vault abrufen, aktualisieren oder löschen |
POST /api/vaults/test-connection | Ein Backend testen, bevor der Vault erstellt wird |
GET /api/vaults/{id}/health · /version | Backend-Gesundheit und -Version |
POST /api/vaults/{id}/benchmark · /crypto-test | Leistungs-Benchmark und kryptografischer Round-Trip-Test |
GET /api/vaults/{id}/keys · /remote-key-count | Schlüssel in einem Vault und die Anzahl der Schlüssel im entfernten Backend |
POST /api/vaults/{id}/sync-keys | Vorhandene Backend-Schlüssel ermitteln / importieren |
App-Vault-Verknüpfung
Anwendungen werden mit den Vaults verknüpft, die sie nutzen dürfen; ein für eine App erstellter Schlüssel ist an einen bestimmten Vault gebunden.
| Methode + Pfad | Zweck |
|---|---|
GET /api/apps/{id}/vaults | Die mit einer App verknüpften Vaults auflisten |
POST · DELETE /api/apps/{id}/vaults/{vault_id} | Einen Vault mit einer App verknüpfen · die Verknüpfung aufheben |
Vault-Typen & Schlüsseltypen
Verwenden Sie diese schreibgeschützten Routen, um zu ermitteln, welche Backends die Plattform unterstützt und welche Schlüsseltypen jedes Backend akzeptiert, bevor Sie einen Vault registrieren oder einen Schlüssel erstellen.
| Methode + Pfad | Zweck |
|---|---|
GET /api/vaults/types | Verfügbare Vault- (Backend-)Typen |
GET /api/vaults/types/{type}/key-types | Von einem gegebenen Vault-Typ unterstützte Schlüsseltypen |
Schlüssel
Kryptografische Schlüssel werden innerhalb eines Vaults erstellt und über vault_id referenziert. Diese Routen verwalten den Lebenszyklus eines Schlüssels — erstellen, auflisten, abrufen, rotieren und die Aktivieren-/Deaktivieren-Übergänge — und führen kryptografische Operationen damit aus. Privates und symmetrisches Schlüsselmaterial verbleibt im Backend; nur öffentliche Schlüssel sind exportierbar.
| Methode + Pfad | Zweck |
|---|---|
GET · POST /api/keys | Schlüssel auflisten · neuen Schlüssel erstellen |
GET · PUT · DELETE /api/keys/{id} | Metadaten eines Schlüssels abrufen, aktualisieren oder den Schlüssel löschen |
POST /api/keys/{id}/rotate | Einen Schlüssel auf eine neue Version rotieren |
POST /api/keys/{id}/activate · /deactivate | Einen Schlüssel aktivieren (Active) oder deaktivieren (Deactivated) |
POST /api/keys/{id}/revoke | Einen Schlüssel mit Begründung widerrufen |
GET /api/keys/{id}/public-key | Den öffentlichen Schlüssel im PEM-Format exportieren |
POST /api/keys/{id}/encrypt · /decrypt | Klartext verschlüsseln · Chiffretext mit dem Schlüssel entschlüsseln |
GET /api/keys/{id}/apps | Die Apps auflisten, die diesen Schlüssel verwenden |
Es gibt keine separate enable-/disable-Route: activate versetzt einen Schlüssel in den Status Active, deactivate in den Status Deactivated. Nur ein Active-Schlüssel darf für kryptografische Operationen verwendet werden.
Post-Quanten-Schlüsseltypen (ML-KEM, ML-DSA, SLH-DSA) können nur in einem Vault erstellt werden, der auf dem Software Vault oder Securosys basiert. Verwenden Sie GET /api/vaults/types/{type}/key-types, um zu bestätigen, dass ein Backend den benötigten Schlüsseltyp akzeptiert, bevor Sie den Schlüssel erstellen.