Authentifizierung und Autorisierung

Die Superheld API dokumentiert zwei Authentifizierungsmechanismen: API-Schluessel fuer direkte Integrationen und OAuth2 fuer delegierten Zugriff durch Drittanwendungen. Die aktuelle Workspace-Runtime nutzt im Secure Mux einen einfachen Bearer-Token-Store; produktive Key-Lifecycle-Details bleiben noch im Abgleich.

Current workspace note: Zusätzlich existiert jetzt ein interner, tenant-gebundener Secure-Mux-Prototyp für Token-Lifecycle über GET /tokens, POST /tokens, GET /tokens/audit, GET /tokens/{id}, GET /tokens/{id}/audit und DELETE /tokens/{id}. Er ist als Runtime-Operatorpfad nutzbar, aber noch kein finaler öffentlicher Produktvertrag. In cmd/server werden dabei nur SHA-256(token) plus Metadaten persistiert; der rohe Tokenwert wird nur einmal bei der Erstellung zurückgegeben. Audit-Einträge zu Tokens folgen demselben Runtime-Backend.

API-Schlüssel

Format

Der produktive API-Key-Lifecycle ist noch nicht final mit der Workspace-Implementierung abgeglichen. In öffentlichen Beispielen werden folgende Präfixe verwendet:

Präfix	Umgebung
`sh_live_`	Produktionsumgebung
`sh_test_`	Testumgebung

Beispiel:

sh_live_abc123xyz456

Erstellung

API-Schlüssel werden im Superheld-Dashboard unter Einstellungen → API-Zugang → Neuer Schlüssel erstellt. Bei der Erstellung wählen Sie einen Namen, die gewünschten Scopes und optional ein Ablaufdatum. Der Schlüssel wird nur einmal vollständig angezeigt — speichern Sie ihn sofort in einem Credential-Manager.

Verwendung

API-Schlüssel können in der aktuellen Workspace-Runtime entweder im Authorization-Header oder im X-API-Key-Header übergeben werden:

curl -X GET https://api.superheld.app/devices \
  -H "Authorization: Bearer sh_live_abc123xyz456"

curl -X GET https://api.superheld.app/devices \
  -H "X-API-Key: sh_live_abc123xyz456"

Schlüssel dürfen nicht im Query-String oder Request-Body übermittelt werden. Alle Anfragen müssen über HTTPS erfolgen.

Rotation

Empfohlene Vorgehensweise zur Schlüsselrotation:

Neuen Schlüssel mit identischen Scopes im Dashboard erstellen.
Integration aktualisieren — neuen Schlüssel in der Anwendung hinterlegen.
Alten Schlüssel widerrufen, sobald die Integration mit dem neuen Schlüssel arbeitet.

Empfohlener Rotationszyklus: alle 90 Tage. In sicherheitskritischen Umgebungen: 30 Tage.

Widerruf

Kompromittierte Schlüssel können unter Einstellungen → API-Zugang sofort widerrufen werden. Der Widerruf ist unwiderruflich und wirkt sofort — alle Anfragen mit diesem Schlüssel erhalten ab diesem Zeitpunkt 401 Unauthorized.

OAuth2

Current workspace note: Die öffentliche OAuth2-Darstellung beschreibt den Zielvertrag. Die aktuelle Workspace-Runtime belegt dafür noch keinen vollständigen produktiven Endpunktpfad.

Für Szenarien, in denen Drittanwendungen im Namen eines Benutzers auf die API zugreifen.

Authorization Code Flow

Für Webanwendungen, bei denen ein Benutzer den Zugriff explizit autorisiert:

# 1. Benutzer zur Autorisierung weiterleiten
https://auth.superheld.app/authorize?
  response_type=code&
  client_id=CLIENT_ID&
  redirect_uri=https://meine-app.de/callback&
  scope=devices:read threats:read

# 2. Authorization Code gegen Token tauschen
curl -X POST https://auth.superheld.app/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=https://meine-app.de/callback"

Die Antwort enthält ein access_token und ein refresh_token. Das Access-Token ist 60 Minuten gültig.

Product target note: Refresh-Token-Lifecycle und Rotationsdetails werden erst dann als verbindlicher öffentlicher Vertrag dokumentiert, wenn sie mit der produktiven Auth-Implementierung abgestimmt sind.

Client Credentials Flow

Für Server-zu-Server-Integrationen ohne Benutzerinteraktion:

curl -X POST https://auth.superheld.app/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=threats:read scan:write"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "threats:read scan:write"
}

Token verwenden

OAuth2-Token werden wie API-Schlüssel im Authorization-Header übergeben:

curl -X GET https://api.superheld.app/threats \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Scope-basierte Autorisierung

Scopes begrenzen den Zugriff eines Schlüssels oder Tokens auf bestimmte Ressourcen und Aktionen. Die folgende Tabelle enthält alle Scopes, die für die kanonischen Endpunkte (siehe API-Übersicht) erforderlich sind.

Scope	Berechtigung	Status
`devices:read`	Geräte auflisten und Details abrufen	Implemented
`devices:write`	Geräte registrieren und konfigurieren	Implemented
`threats:read`	Bedrohungen auflisten und Details abrufen	Implemented
`alerts:read`	Abgeleitete Alerts abrufen	Implemented
`alerts:write`	Reserviert, aktuell keine Alert-Create-Route	Reserved
`incidents:read`	Tenant-gebundene Security-Incidents abrufen	Implemented (prototypisch/intern)
`incidents:write`	Tenant-gebundene Security-Incidents weiter in ihrem Lifecycle bewegen	Implemented (prototypisch/intern)
`scan:write`	Inhalte zur Analyse übergeben	Implemented
`status:read`	Schutzstatus abrufen	Implemented
`events:read`	Ereignisse abrufen (SIEM-Integration)	Implemented
`events:write`	Ereignisse über den Secure Mux einliefern	Implemented
`jobs:read`	Asynchrone Job-, Trace-, Step- und Artefakt-Records abrufen	Implemented (prototypisch)
`jobs:write`	Asynchrone Job-Records anlegen und abbrechen	Implemented (prototypisch)
`jobs:review`	Waiting-Review-Jobs reviewen; `jobs:write` bleibt dafür als Legacy-Fallback akzeptiert	Implemented (prototypisch)
`tokens:read`	Tenant-gebundene Secure-Mux-Token-Metadaten und Token-Audit abrufen	Implemented (prototypisch/intern)
`tokens:write`	Tenant-gebundene Secure-Mux-Tokens erzeugen und widerrufen	Implemented (prototypisch/intern)
`webhooks:read`	Webhooks und DLQ-Einträge abrufen	Implemented
`webhooks:write`	Webhooks erstellen und DLQ-Replays auslösen	Implemented

Anfragen, deren Scope nicht ausreicht, werden mit 403 Forbidden beantwortet:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Der Scope 'threats:read' ist für diesen Endpunkt erforderlich.",
    "status": 403
  }
}

Vergeben Sie immer nur die minimal notwendigen Scopes. Eine Integration, die ausschließlich Bedrohungen überwacht, benötigt lediglich threats:read.