Authentifizierung & Scopes
Jede öffentliche API-Anfrage muss einen langlebigen API-Schlüssel als Bearer-Token tragen. Scopes beschränken, was jeder Schlüssel tun darf — gewähren Sie nur das, was Ihre Integration tatsächlich benötigt.
Bearer-Token-Format
API-Schlüssel sehen so aus:
scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDHDas Präfix scs_live_ identifiziert den Schlüssel als Produktions-Anmeldedaten für SecureCodingHub. Tokens sind insgesamt 41 Zeichen lang (9-stelliges Präfix + 32-stelliger zufälliger Körper). Sie werden bei der Schlüsselerstellung genau einmal zurückgegeben.
Senden Sie das Token bei jeder Anfrage als standardmäßigen Bearer-Authentifizierungsheader:
Authorization: Bearer scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDHEinen API-Schlüssel erstellen
API-Schlüssel werden in der Administratorkonsole erstellt — nicht über die API.
Melden Sie sich bei app.securecodinghub.com als Organisationsadministrator an.
Öffnen Sie Organisation → API-Schlüssel aus der Seitenleiste.
Klicken Sie auf + Neuen Schlüssel erstellen. Geben Sie dem Schlüssel einen beschreibenden Namen (z.B. GitHub Actions — CI oder Looker BI sync).
Markieren Sie nur die Scopes, die die Integration benötigt. Read-only-Scopes sind blau hervorgehoben, Write-Scopes bernsteinfarben.
(Optional) Setzen Sie ein Ablaufdatum. Schlüssel ohne Ablaufdatum bleiben gültig, bis Sie sie widerrufen.
Klicken Sie auf Schlüssel erstellen. Das vollständige Token wird in einem Modal angezeigt. Kopieren Sie es jetzt in Ihren Secrets-Manager. Sie werden es nicht mehr abrufen können — nur das Präfix und die letzten vier Zeichen werden gespeichert.
Scope-Referenz
SecureCodingHub verwendet 16 feingranulare Scopes, die in Read- und Write-Stufen aufgeteilt sind. Eine Anfrage, die auf einen Endpoint ohne den passenden Scope trifft, gibt 403 Forbidden mit dem Antwortkörper {"error":"insufficient_scope","required":"…","present":[…]} zurück.
| Scope | Ressource | Stufe | Gewährungen |
|---|---|---|---|
org:read | Organisation | Read | Lesen Sie Organisations-Metadaten (Name, Plan, Sitzplätze). |
users:read | Benutzer | Read | Benutzer auflisten; Benutzerdetail abrufen. |
users:write | Benutzer | Write | Benutzer erstellen, aktualisieren, deaktivieren. |
teams:read | Teams | Read | Teams und Mitglieder auflisten. |
teams:write | Teams | Write | Teams erstellen, aktualisieren, löschen. |
assignments:read | Zuweisungen | Read | Zuweisungen auflisten; Detail mit Abschluss abrufen. |
assignments:write | Zuweisungen | Write | Zuweisungen erstellen, aktualisieren, deaktivieren. |
custom-courses:read | Benutzerdefinierte Kurse | Read | Benutzerdefinierte Kurse mit Elementen auflisten. |
custom-courses:write | Benutzerdefinierte Kurse | Write | Benutzerdefinierte Kurse erstellen, aktualisieren, löschen. |
progress:read | Fortschritt | Read | Übungs- und Lernfortschritt pro Benutzer. |
certificates:read | Zertifikate | Read | Zertifikate auflisten und herunterladen. |
audit-log:read | Audit-Protokoll | Read | Audit-Protokoll-Einträge auflisten. |
compliance:read | Compliance | Read | Compliance-Dashboard-Daten. |
content:read | Inhalt | Read | Themen, Szenarien, CWE-zu-Thema-Zuordnung. |
sarif:ingest | SARIF | Write | SARIF-Läufe aufnehmen und Schulungen automatisch zuweisen. |
webhook:manage | Webhooks | Write | Ausgehende Webhook-Endpoints verwalten. |
Empfohlene Scope-Sets
| Anwendungsfall | Mindest-Scopes |
|---|---|
| CI/CD SARIF-Ingestion | sarif:ingest |
| HR-getriebene Benutzerbereitstellung | users:write, teams:write |
| BI / Berichts-Export | users:read, progress:read, assignments:read, audit-log:read |
| Ticketing & SOAR (Ereignis-Abonnenten) | webhook:manage, assignments:read |
| Auditor Read-only-Export | org:read, audit-log:read, compliance:read, certificates:read |
Rotation & Widerruf
Um einen Schlüssel zu rotieren, erstellen Sie zuerst einen Ersatz, stellen Sie das neue Token bereit und widerrufen Sie dann den alten in Organisation → API-Schlüssel. Der Widerruf wird sofort wirksam — laufende Anfragen mit dem alten Token beginnen innerhalb von Sekunden, 401 Unauthorized zurückzugeben.
Wenn ein Schlüssel geleckt ist, widerrufen Sie ihn. Es gibt keinen "Pause"-Zustand; der Widerruf ist permanent. Das Token kann nicht wieder aktiviert werden.
Best Practice zur Speicherung
- Behandeln Sie das Token wie ein Datenbankpasswort. Niemals in der Quellkontrolle committen.
- Bevorzugen Sie den nativen Secret-Speicher Ihrer Plattform (AWS Secrets Manager, GCP Secret Manager, GitHub Actions secrets, Vault, 1Password Connect).
- In CI injizieren Sie das Token nur in dem Schritt, der es benötigt; vermeiden Sie
echo. - Stellen Sie einen Schlüssel pro Integration aus, damit Sie unabhängig widerrufen können. Teilen Sie keinen einzigen Schlüssel über CI, BI und SOAR.
- Setzen Sie ein Ablaufdatum auf Tokens, die für kurzlebige Integrationen (Proofs of Concept, Anbieter-Evaluierungen) erstellt wurden.
Häufige Fehler
| Status | Antwort | Bedeutung |
|---|---|---|
401 | {"error":"unauthorized"} | Fehlendes, fehlerhaftes, widerrufenes oder abgelaufenes Token. |
403 | {"error":"insufficient_scope",…} | Token ist gültig, aber es fehlt der erforderliche Scope für diesen Endpoint. |
429 | {"error":"rate_limited"} | Pro-Minute- oder Pro-Stunde-Obergrenze erreicht. Siehe Rate Limits. |