Authentifizierung und API-Schlüssel

Die Cert-IX Scan-API verwendet API-Schlüssel für den programmatischen Zugriff. API-Schlüssel bieten granulare Bereiche, Einschränkungen nach Scan-Typ, Rate-Limits pro Schlüssel, IP-Allowlisting, automatischen Ablauf und unterbrechungsfreie Rotation.

Authentifizierungsmethoden

Methode	Anwendungsfall	Header
API-Schlüssel	Programmatischer Zugriff (Skripte, CI/CD, Integrationen)	X-API-Key
JWT	Dashboard-Operationen (API-Schlüsselverwaltung)	Authorization: Bearer <token>

Format der API-Schlüssel

cix_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Segment	Beschreibung
cix_	Cert-IX-Plattform-Präfix
sk_	Secret-Key-Typkennung
XXX...	40-Zeichen kryptographisch zufällige Zeichenkette

Sicherheit

API-Schlüssel werden mit SHA-256 vor der Speicherung gehasht. Der Klartext-Schlüssel wird nur einmal bei der Erstellung angezeigt. Cert-IX kann Ihren Schlüssel bei Verlust nicht wiederherstellen — Sie müssen eine Rotation durchführen.

API-Schlüssel übertragen

Fügen Sie Ihren API-Schlüssel im X-API-Key-Header in jeder Anfrage hinzu:

curl -X GET https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: cix_sk_ihr_api_schluessel_hier"

Übertragen Sie API-Schlüssel niemals in URL-Parametern

Query-Strings können in Server-Zugriffs-Logs, Browser-Verlauf und Proxy-Caches protokolliert werden.

API-Schlüssel erstellen

Endpunkt

POST /api/v1/api-keys

Anfragekörper

{
  "name": "CI/CD-Pipeline - Produktion",
  "description": "Verwendet von GitHub Actions für nächtliche Schwachstellenscans",
  "scopes": ["scans:create", "scans:read", "scans:list", "results:read", "webhooks:read"],
  "allowedScanTypes": ["nmap", "nuclei", "trivy", "zap"],
  "allowedIpAddresses": ["203.0.113.50", "198.51.100.0/24"],
  "rateLimitPerMinute": 30,
  "rateLimitPerHour": 500,
  "rateLimitPerDay": 5000,
  "expiresInDays": 90
}

Anfrageparameter

Feld	Typ	Erforderlich	Beschreibung
name	string	Ja	Lesbarer Name des Schlüssels (max. 255 Zeichen)
description	string	Nein	Optionale Verwendungsbeschreibung
scopes	string[]	Nein	Berechtigungsbereiche (Standard: alle Bereiche)
allowedScanTypes	string[]	Nein	Erlaubte Scan-Engines (Standard: alle)
allowedIpAddresses	string[]	Nein	Erlaubte Quell-IP/CIDR-Bereiche
rateLimitPerMinute	integer	Nein	Max. Anfragen pro Minute
rateLimitPerHour	integer	Nein	Max. Anfragen pro Stunde
rateLimitPerDay	integer	Nein	Max. Anfragen pro Tag
expiresInDays	integer	Nein	Ablauf in Tagen (0 oder null = kein Ablauf)

Antwort (201 Created)

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "CI/CD-Pipeline - Produktion",
      "keyPrefix": "cix_sk_001e3c",
      "scopes": ["scans:create", "scans:read", "scans:list", "results:read", "webhooks:read"],
      "status": "active",
      "expiresAt": "2026-06-04T10:00:00Z",
      "createdAt": "2026-03-06T10:00:00Z"
    },
    "rawKey": "cix_sk_001e3c2d92ffb23344a943df2b6a001fb1028d002"
  }
}

Kritisch

Das Feld rawKey wird nur bei der Erstellung zurückgegeben. Kopieren Sie es sofort und speichern Sie es in einem sicheren Tresor (z.B.: HashiCorp Vault, AWS Secrets Manager).

Bereiche und Berechtigungen

Bereiche kontrollieren die Aktionen, die ein API-Schlüssel ausführen darf. Wenden Sie das Prinzip der geringsten Rechte an.

Verfügbare Bereiche

Bereich	Beschreibung
scans:create	Neue Scans einreichen
scans:read	Scan-Details und -Status anzeigen
scans:list	Alle Scans des Mandanten auflisten
scans:cancel	Laufende Scans abbrechen
results:read	Ergebnisse und Befunde abrufen
templates:create	Scan-Vorlagen erstellen
templates:read	Scan-Vorlagen anzeigen
templates:update	Scan-Vorlagen ändern
templates:delete	Scan-Vorlagen löschen
webhooks:create	Webhooks registrieren und testen
webhooks:read	Konfigurationen und Zustellungsprotokolle anzeigen
webhooks:update	Webhook-Einstellungen ändern
webhooks:delete	Webhooks löschen
usage:read	Nutzungsanalytik und Kontingente anzeigen

Empfohlene Bereichssets

CI/CD-Pipeline (Scan Lesen/Schreiben):

["scans:create", "scans:read", "scans:list", "results:read"]

Überwachungs-Dashboard (Nur Lesen):

["scans:read", "scans:list", "results:read", "usage:read"]

Vollautomatisierung (Scans + Webhooks + Vorlagen):

["scans:create", "scans:read", "scans:list", "scans:cancel", "results:read",
 "templates:create", "templates:read", "templates:update",
 "webhooks:create", "webhooks:read"]

Erlaubte Scan-Typen

Schränken Sie die Scan-Engines ein, die ein API-Schlüssel aufrufen kann:

Verfügbare Scan-Typen: nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel

IP-Allowlisting

Sperren Sie einen API-Schlüssel auf bestimmte Quell-IP-Adressen oder CIDR-Bereiche. Anfragen von anderen IPs werden mit 403 IP_NOT_ALLOWED abgelehnt.

Unterstützte Formate:

• Einzelne IP: "203.0.113.50"
• CIDR-Bereich: "198.51.100.0/24"
• IPv6: "2001:db8::1"

Rate-Limits

Fenster	Standard	Konfigurierbarer Bereich
Pro Minute	60	1 – 1.000
Pro Stunde	1.000	1 – 50.000
Pro Tag	10.000	1 – 500.000

Rate-Limit-Header

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1709654460

Rate-Limit überschritten

{
  "success": false,
  "error": "Rate-Limit überschritten. Versuchen Sie es in 23 Sekunden erneut.",
  "code": "RATE_LIMIT_EXCEEDED"
}

HTTP-Status: 429 Too Many Requests

Schlüsselrotation

Führen Sie die Rotation von API-Schlüsseln mit null Ausfallzeit dank des Karenzzeit-Mechanismus durch.

Endpunkt

POST /api/v1/api-keys/:keyId/rotate

Rotations-Workflow

1. POST /api-keys/:alterSchluesselId/rotate → Neuer Schlüssel erstellt, alter in Karenzzeit
2. Aktualisieren Sie Ihren Secret-Speicher mit dem neuen Schlüssel
3. Deployen Sie den neuen Schlüssel in Ihren Diensten
4. Der alte Schlüssel läuft nach der Karenzzeit automatisch ab

Bewährte Praxis

Führen Sie die Schlüsselrotation alle 90 Tage durch. Automatisieren Sie die Rotation in Ihrer Infrastruktur oder setzen Sie eine Kalender-Erinnerung.

Schlüsselwiderruf

Deaktivieren Sie einen API-Schlüssel sofort und dauerhaft. Der Widerruf ist sofort — der Schlüssel funktioniert augenblicklich nicht mehr.

Endpunkt

DELETE /api/v1/api-keys/:keyId

Schlüsselstatus

Status	Beschreibung
active	Der Schlüssel ist voll funktionsfähig
revoked	Der Schlüssel wurde dauerhaft deaktiviert
expired	Der Schlüssel hat sein expiresAt-Datum überschritten
suspended	Der Schlüssel wurde von einem Administrator vorübergehend gesperrt

Best Practices für die Sicherheit

Empfohlen

• ✅ Schlüssel in einem Secret-Manager speichern (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault)
• ✅ Umgebungsvariablen verwenden — Schlüssel niemals hart kodieren
• ✅ Geringste Rechte anwenden — Nur die benötigten Bereiche gewähren
• ✅ Ablaufdaten festlegen — Rotation alle 90 Tage
• ✅ IP-Allowlisting verwenden für statische Infrastruktur
• ✅ Nutzung überwachen über die Nutzungsanalytik-Endpunkte
• ✅ Sofort widerrufen, wenn ein Schlüssel kompromittiert ist

Zu vermeiden

• ❌ Schlüssel niemals in die Versionskontrolle committen (Git, SVN)
• ❌ Schlüssel niemals in URL-Parametern übertragen
• ❌ Schlüssel niemals zwischen Teams oder Umgebungen teilen
• ❌ API-Schlüssel niemals in Anwendungs-Logs protokollieren

---

Nächste Schritte:

• Scans einreichen →
• Scan-Vorlagen →
• Fehlerreferenz →