Authentifizierung

Alle Endpoints der ferrixx API erfordern einen gültigen API-Key mit der passenden Berechtigung.

Methode 1 – HTTP-Header (empfohlen)

Der API-Key wird im Request-Header übergeben. Dies ist die bevorzugte Methode, da der Key nicht in Server-Logs oder Browser-Historien auftaucht.

curl -H "X-API-Key: apk_xxxxxxxxxxxxxxxxxxxx" \
     https://api.ferrixx.de/v1/status

Methode 2 – Query-Parameter

Der API-Key kann alternativ als URL-Parameter übergeben werden. Nur für einfache Tests empfohlen.

curl "https://api.ferrixx.de/v1/status?api_key=apk_xxxxxxxxxxxxxxxxxxxx"

Key-Format

Alle API-Keys beginnen mit dem Präfix apk_ gefolgt von 48 zufälligen Hex-Zeichen (insgesamt 52 Zeichen).

apk_a1b2c3d4e5f6... ← 52 Zeichen gesamt

Berechtigungen (Permissions)

Jeder API-Key hat ein Set an Berechtigungen, die im Control Panel konfiguriert werden. Ein Key kann nur Endpoints aufrufen, für die er die Berechtigung hat.

Permission	Beschreibung	Zugriff auf
`*`	Vollzugriff auf alle Endpoints	Alle
`status`	API-Status abrufen	`/v1/status`
`ping`	Vorkonfigurierte Server anpingen	`/v1/ping`, `/v1/ping?id=`
`ping.custom`	Beliebige Hosts anpingen (erfordert `ping`)	`/v1/ping?host=`
`minecraft`	Minecraft-Server abfragen	`/v1/minecraft`

Fehler-Antworten

Bei fehlerhafter oder fehlender Authentifizierung liefert die API folgende Antworten:

Kein API-Key angegeben → 401

{
  "success": false,
  "error": "No API key provided",
  "timestamp": "2026-06-01T12:00:00+00:00"
}

Ungültiger Key → 401

{
  "success": false,
  "error": "Invalid API key",
  "timestamp": "2026-06-01T12:00:00+00:00"
}

Fehlende Berechtigung → 403

{
  "success": false,
  "error": "Permission denied",
  "timestamp": "2026-06-01T12:00:00+00:00"
}

API-Keys verwalten

API-Keys werden im Control Panel → API Keys erstellt und verwaltet. Der vollständige Key wird nur einmalig bei der Erstellung angezeigt.