Api-schlüsselverwaltung
Token-Format, Erstellungsablauf, 8 Berechtigungs-Scopes, Lebenszyklus, Nutzungsanalyse und Sicherheits-Best-Practices.
Der API-Schlüssel ist Ihr einziger Berechtigungsnachweis für die Kommunikation mit der offenen Plattform von Braidrun. Jeder Schlüssel enthält eine Reihe von Bereichen (Berechtigungsbereich) und ein Token. Bei Verlust oder Durchsickern wird die neue Erstellung sofort widerrufen.
Token-format
dyk_<id>_<secret>
例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789dyk_— Markenpräfix, um das Git-Secret-Scanning-/Log-Desensibilisierungstool identifizierbar zu machen<id>— 16-stellige öffentliche base62-ID, verwendbar als Lookup-Key (nicht sensibel)<secret>— 32-Byte-Zufallsgeheimnis, Base64-URL-Kodierung (sensibel, das Hochladen von Protokollen/Fehlermeldungen ist nicht zulässig)
Beim Generieren eines API-Schlüssels wird der Original-Token nur einmal im Erstellungsdialog angezeigt. Nach dem Schließen behält der Server nur den Argon2id-Hash und kann den Originaltext nicht überprüfen. Bitte kopieren und speichern Sie es jetzt in Ihrem Schlüsselverwaltungstool (1Password/Vault/Doppler/GitHub Secrets/usw.).
Api-schlüssel erstellen
- Besuchen Sie die Konsole → Kontoeinstellungen → API-Schlüssel
- Klicken Sie auf „Neuer API-Schlüssel“.
- Ausfüllen: Name (zur Identifizierung), Umfangsliste, Gültigkeitsdauer (dauerhaft / 30 Tage / 90 Tage / 1 Jahr)
- Klicken Sie auf „Schlüssel generieren“ → Token jetzt kopieren
Bereiche
Scopes sind feingranulare Berechtigungen, insgesamt 8: 7 lassen sich selbst vergeben, CLUSTER_ADMIN ist Administratoren vorbehalten. Vergeben Sie einem Key so wenige wie möglich — nach dem Prinzip der minimalen Rechte.
| Scope | was kann getan werden | Typische Szenarien |
|---|---|---|
WEBHOOK_TRIGGER | Lösen Sie den an diesen Schlüssel gebundenen Webhook aus | GitHub Push → Workflow; Rückruf des Upstream-Geschäftssystems |
APPROVAL_RESPOND | manual_approval-Schritte genehmigen / ablehnen — deckt den Genehmigungs-Webhook und die v1-Genehmigungs-Endpunkte ab (/api/v1/approvals/*, inkl. Auflisten offener Genehmigungen, Lesen von Details, Einreichen des bearbeiteten Genehmigungsformulars) | Ein-Klick-Genehmigungslinks per E-Mail / Slack; Anbindung externer Genehmigungssysteme |
WORKFLOW_READ | Workflow-Definitionen auflisten/lesen | Zeigen Sie die aktuelle Workflow-Liste in einem externen Dashboard an |
WORKFLOW_EXECUTE | Workflows über API starten (Ersatz des Webhook-Modus) | SDK-Integration; automatisiertes Testen; Batch-Aufgaben |
EXECUTION_READ | Ausführungsstatus abfragen/vollständiges Ergebnis lesen | Backflow-Ausführungsergebnisse an Enterprise BI/Data Warehouse |
EXECUTION_CANCEL | Brechen Sie eine laufende Ausführung ab | „Stopp“-Taste am Steuerpult/Notschalter |
ARTIFACT_READ | Ausführungsprodukte auflisten/Download-Link erhalten | Archivberichte zum Objektspeicher; Übertragen Sie die Ergebnisse an nachgelagerte Systeme |
CLUSTER_ADMIN | Nur für Administratoren: Clusterstatus lesen, Autoscaling-Richtlinien verwalten. Nur Administratoren können ihn vergeben; erstellt ein Nicht-Administrator einen Key, wird dieser Scope automatisch entfernt | Betriebs-Servicekonto für On-Premise-Deployments |
Lebenszyklus
- erstellen — Benutzer-Selbstbedienung; Umfang + Gültigkeitsdauer entscheiden Sie
- Benutzen — Bei jedem erfolgreichen Aufruf wird die Nutzung automatisch erfasst und der lastUsedAt-Zeitstempel aktualisiert.
- Revoke — Benutzer können jederzeit auf der Seite „API-Schlüssel“ auf „Widerrufen“ klicken; idempotent
- Läuft ab — expiresAt läuft sofort nach der Ankunft ab; Es ist kein aktiver Widerruf erforderlich
Dosierungsanalyse
Klicken Sie für jeden Schlüssel in der Tabelle „API-Schlüssel“ auf „Verwendung“. Daraufhin wird eine Diagrammanalyse angezeigt:
- Kumulierte Anzahl von Anrufen + innerhalb des Fensters (7/30/90/180 Tage optional)
- Spitzentag (an welchem Tag gibt es die meisten Anrufe)
- Liniendiagramm der täglichen Anrufe
- Kreisdiagramm zur Anrufendpunktverteilung (webhook.trigger/workflow.execute/etc)
- Zuletzt genutzte Zeit
Bei der Nutzung werden nur erfolgreiche Antworten gezählt (HTTP 2xx). Authentifizierungsfehler/Anfragen mit eingeschränkter Rate werden nicht gezählt.
Wichtige Best Practices für die Sicherheit
- Verwenden Sie für jede Umgebung (Produktion/Staging/lokal) unabhängige Schlüssel – im Falle eines Vorfalls wird nur die betroffene Umgebung widerrufen
- Jede externe Integration verwendet einen separaten Schlüssel – verwenden Sie „Verwendung“, um zu sehen, welche Integration verwendet wird
- Senden Sie Token niemals an das Code-Repository
- Als verschlüsseltes Geheimnis in CI/CD einfügen; Nicht in Protokolle drucken
- Beachten Sie, dass die „zuletzt genutzte“ Zeit von Ihrer Erwartung abweicht → sofort widerrufen und die Protokolle überprüfen
- Schlüssel, die an Kurzzeitpartner vergeben werden, müssen auf „expiresAt“ (empfohlen innerhalb von 90 Tagen) eingestellt sein.