API-Schlüssel & Scopes

Mit API-Schlüsseln rufen Skripte, CI-Pipelines, die CLI und MCP-Clients die API von ERP Preflight ohne interaktive Anmeldung auf. Ein Schlüssel gehört zu genau einer Organisation und erreicht nur die Routen, die seine Scopes erlauben; alle anderen Routen bleiben ihm verschlossen.

• Nur Organisationsinhaber und Security-Admins können Schlüssel anlegen, auflisten und widerrufen, und zwar nur bei interaktiver Anmeldung — ein API-Schlüssel kann niemals API-Schlüssel verwalten.
• Zum Anlegen eines Schlüssels ist eine bestätigte E-Mail-Adresse erforderlich.
• Anlegen und Widerrufen werden im Audit-Log protokolliert (api_key.created, api_key.revoked).

Öffnen Sie in der Web-App Einstellungen → Workspace & API → API-Schlüssel, geben Sie einen Namen des Schlüssels ein und wählen Sie Schlüssel erstellen. Der vollständige Schlüssel beginnt mit erppf_live_ und wird nur ein einziges Mal angezeigt — übernehmen Sie ihn sofort in Ihren Secret-Speicher. ERP Preflight speichert nur einen SHA-256-Hash des Schlüssels; die Schlüsselliste zeigt seine ersten 15 Zeichen als Präfix.

In der Web-App angelegte Schlüssel erhalten die Standard-Scopes projects:read, analyses:read, analyses:run, findings:read und reports:read. Das genügt, um aus einer Pipeline Dateien hochzuladen, Analysen zu starten, Befunde zu lesen und Berichte zu exportieren. Andere Scopes, ein Ablaufdatum oder ein eigenes Anfragelimit legen Sie fest, indem Sie den Schlüssel bei angemeldeter Sitzung über die API anlegen:

POST /api/v1/api-keys
{
  "name": "GitLab CI – S/4HANA-Upgrade",
  "scopes": ["projects:read", "projects:write", "analyses:read", "analyses:run", "findings:read", "reports:read"],
  "expiresAt": "2027-03-31T00:00:00Z",
  "rateLimitPerMinute": 120
}

name ist Pflicht (bis 255 Zeichen); scopes, expiresAt (ISO 8601) und rateLimitPerMinute (1 bis 100 000) sind optional. Die Antwort enthält den Schlüssel im Feld apiKey — auch hier nur dieses eine Mal.

Senden Sie den Schlüssel bei jeder Anfrage an /api/v1 im Header X-Api-Key:

curl -H "X-Api-Key: $ERP_PREFLIGHT_API_KEY" https://api.example.com/api/v1/projects

Der Schlüssel bestimmt die Organisation. Enthält eine Anfrage zusätzlich X-Tenant-Id, muss dieser Header die Organisation des Schlüssels nennen, sonst wird die Anfrage mit HTTP 403 abgewiesen. Anfragen mit einem Schlüssel handeln als API-Client der Organisation im Namen der Person, die den Schlüssel angelegt hat. Ein Token gegen Cross-Site-Request-Forgery ist dafür nicht nötig.

Jede Route, die API-Schlüssel aufrufen dürfen, ist genau einem Scope für lesende Zugriffe (GET, HEAD, OPTIONS) und einem für alle anderen Methoden zugeordnet. Der Schlüssel muss diesen Scope besitzen; Routen ohne Zuordnung sind für API-Schlüssel gesperrt.

• projects:read — Projekte, hochgeladene Artefakte, den Objektkatalog des Projekts, Analysevorlagen und Referenzdaten lesen (Engine-Katalog, Knowledge Graph, Wissensartikel, Release Intelligence).
• projects:write — Projekte, API-Baselines, Objektimporte, Change Sets, Traceability-Verknüpfungen und Analysevorlagen anlegen und ändern.
• analyses:read — Analysen und ihren Fortschritt, Full-Preflight-Läufe und geplante Preflights lesen.
• analyses:run — Analyse-Eingaben hochladen, Analysen starten, abbrechen und erneut ausführen, geplante Preflights verwalten und den Problem-Router nach passenden Engines fragen.
• findings:read — Befunde mit ihrer Evidenz, generierte Tests und das Regressions-Test-Lab lesen.
• findings:write — Lebenszyklusstatus, Kommentare und Zuweisungen von Befunden ändern sowie Regressionstests verwalten.
• reports:read — Berichte und Exporte einer Analyse erzeugen und herunterladen, einschließlich des Reproduzierbarkeits-Bundles.
• landscapes:read — registrierte SAP-Landschaften (Systemverbindungen) auflisten.
• landscapes:write — SAP-Landschaften registrieren und löschen sowie Verbindungstests ausführen.
• dashboard:read — die Dashboard-Zusammenfassung der Organisation lesen.
• webhooks:manage — Webhook-Endpunkte und ihre Zustellungen verwalten (siehe Webhooks).
• changes:propose — Änderungsvorschläge beim Agent Gate (Änderungsprüfung für Agenten) einreichen und freigegebene Vorschläge mit ihrem Ausführungstoken ausführen.

Der MCP-Endpunkt akzeptiert jeden Schlüssel mit mindestens einem Scope und prüft den Scope jedes Tools einzeln.

Unabhängig von seinen Scopes kann ein Schlüssel weder API-Schlüssel noch Mitglieder, Konto, Abrechnung, Single Sign-on und SCIM, Datenaufbewahrung oder Audit-Log verwalten; diese Vorgänge erfordern immer eine interaktive Anmeldung.

Die älteren Scope-Namen analysis:read und analysis:run werden beim Anlegen eines Schlüssels weiterhin akzeptiert; gespeichert werden sie als analyses:read plus findings:read bzw. als analyses:run.

• Ablauf: Ein mit expiresAt angelegter Schlüssel verliert zu diesem Zeitpunkt seine Gültigkeit; Anfragen schlagen dann mit HTTP 401 fehl. Schlüssel ohne expiresAt laufen nicht ab.
• Letzte Nutzung: Jede erfolgreiche Authentifizierung aktualisiert den Zeitpunkt der letzten Nutzung; die Schlüsselliste zeigt ihn als Zuletzt verwendet (last_used_at in GET /api/v1/api-keys).
• Widerruf: Wählen Sie in der Schlüsselliste Widerrufen oder rufen Sie DELETE /api/v1/api-keys/{id} auf. Der Schlüssel wird ab der nächsten Anfrage abgewiesen und bleibt mit dem Status Widerrufen in der Liste.

Zum Rotieren legen Sie einen neuen Schlüssel an, aktualisieren Ihren Secret-Speicher und widerrufen danach den alten Schlüssel.

Jeder Schlüssel hat ein Budget an Anfragen pro Minute: den beim Anlegen gesetzten Wert rateLimitPerMinute, sonst den Standardwert des Betreibers von 600, sofern nicht anders konfiguriert. Antworten enthalten X-RateLimit-Limit; ist das Budget aufgebraucht, antwortet die API mit HTTP 429 und dem Header Retry-After.

• 401 — der Schlüssel ist unbekannt, widerrufen oder abgelaufen.
• 403 API_KEY_SCOPE_DENIED — dem Schlüssel fehlt der in requiredScope genannte Scope.
• 403 — die Route ist für API-Schlüssel gesperrt (mit dem Code API_KEY_NOT_ALLOWED bei Routen ohne Scope-Zuordnung).
• 429 RATE_LIMITED — das Budget des Schlüssels ist erschöpft; wiederholen Sie die Anfrage nach Retry-After Sekunden.