API-Authentifizierung¶

Die enconf REST-API ermöglicht den programmatischen Zugriff auf alle Hosting-Funktionen. Diese Seite beschreibt die verfügbaren Authentifizierungsmethoden, das Token-Format und die Ratenbegrenzung.

Basis-URL¶

Alle API-Endpunkte sind unter folgender Basis-URL erreichbar:

https://ihr-panel.de:3443/api/v1

Port 3443

Das Panel läuft standardmäßig auf Port 3443. Die API ist über denselben Port erreichbar.

Interaktive API-Dokumentation¶

Eine vollständige, interaktive API-Referenz mit allen Endpunkten, Parametern und Beispiel-Responses ist direkt in Ihrem Panel verfügbar:

https://ihr-panel.de:3443/api/docs

Dort können Sie alle API-Aufrufe direkt im Browser testen (Swagger UI). Authentifizieren Sie sich über den Authorize-Button mit Ihrem API-Key oder JWT-Token.

Für WHMCS / HostBill Entwickler

Die OpenAPI-Spezifikation (YAML) ist unter https://ihr-panel.de:3443/api/docs/openapi.yaml abrufbar und kann direkt in Ihre Entwicklungsumgebung importiert werden.

Authentifizierungsmethoden¶

Die API unterstützt zwei Authentifizierungsmethoden:

Methode	Anwendungsfall	Gültigkeit
JWT-Token	Interaktive Nutzung, Frontend	Konfigurierbar (Standard: 24 Stunden)
API-Schlüssel	Automatisierung, Skripte, Integrationen	Bis Ablaufdatum oder manuelles Löschen

Für die interaktive Nutzung authentifizieren Sie sich per E-Mail und Passwort und erhalten ein JWT-Token.

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "kunde@beispiel.de",
  "password": "IhrPasswort"
}

Erfolgreiche Antwort¶

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 42,
      "email": "kunde@beispiel.de",
      "name": "Max Mustermann",
      "role": "customer"
    }
  },
  "error": null,
  "message": "Login successful"
}

Wenn Zwei-Faktor-Authentifizierung aktiviert ist, erfordert der Login zusätzlich einen TOTP-Code:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "kunde@beispiel.de",
  "password": "IhrPasswort",
  "totp_code": "123456"
}

Falls der TOTP-Code fehlt und 2FA aktiviert ist, antwortet die API mit:

{
  "data": null,
  "error": "2fa_required",
  "message": "Two-factor authentication code required"
}

Token verwenden¶

Senden Sie das Token im Authorization-Header bei allen folgenden Anfragen:

GET /api/v1/sites
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token-Gültigkeit¶

Einstellung	Standardwert
Gültigkeitsdauer	24 Stunden (konfigurierbar durch Admin)
Algorithmus	HS256 (HMAC-SHA256)

Nach Ablauf des Tokens müssen Sie sich erneut anmelden.

API-Schlüssel¶

API-Schlüssel sind ideal für Automatisierung, Deployment-Skripte und Integrationen mit Drittanbieter-Systemen.

API-Schlüssel erstellen¶

POST /api/v1/auth/api-keys
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "name": "Deployment-Skript",
  "expires_at": "2027-12-31T23:59:59Z"
}

Feld	Pflicht	Beschreibung
`name`	Ja	Bezeichnung (1–100 Zeichen)
`expires_at`	Nein	Ablaufdatum im RFC 3339 Format

Antwort¶

{
  "data": {
    "id": 1,
    "name": "Deployment-Skript",
    "key": "ncp_a1b2c3d4e5f6...",
    "key_prefix": "ncp_a1b2c3d4e5f6",
    "expires_at": "2027-12-31T23:59:59Z",
    "created_at": "2026-03-31T10:00:00Z"
  },
  "error": null,
  "message": "API key created"
}

Schlüssel nur einmal sichtbar

Das Feld key wird nur in dieser Antwort zurückgegeben. Speichern Sie den Schlüssel sofort sicher ab. Der Klartext kann nach der Erstellung nicht erneut abgerufen werden.

API-Schlüssel verwenden¶

Senden Sie den Schlüssel im Authorization-Header:

GET /api/v1/sites
Authorization: Bearer ncp_a1b2c3d4e5f6...

API-Schlüssel auflisten¶

GET /api/v1/auth/api-keys
Authorization: Bearer <jwt-token>

Antwort:

{
  "data": [
    {
      "id": 1,
      "name": "Deployment-Skript",
      "key_prefix": "ncp_a1b2c3d4e5f6",
      "last_used_at": "2026-03-30T14:22:00Z",
      "expires_at": "2027-12-31T23:59:59Z",
      "created_at": "2026-03-31T10:00:00Z"
    }
  ],
  "error": null,
  "message": ""
}

key_prefix

Der key_prefix zeigt die ersten 20 Zeichen des Schlüssels und dient zur Identifikation. Der vollständige Schlüssel wird nie erneut angezeigt.

API-Schlüssel löschen¶

DELETE /api/v1/auth/api-keys/:id
Authorization: Bearer <jwt-token>

Schlüssel-Format¶

API-Schlüssel verwenden folgendes Format:

ncp_<64 Hex-Zeichen>

Präfix: ncp_ (NetCell Panel)
32 Bytes zufällige Daten, hexadezimal kodiert
Gesamtlänge: 68 Zeichen

Antwort-Format¶

Alle API-Antworten verwenden ein einheitliches JSON-Format:

{
  "data": { ... },
  "error": null,
  "message": "Beschreibung"
}

Feld	Typ	Beschreibung
`data`	Object/Array/null	Die angeforderten Daten
`error`	String/null	Fehlerbeschreibung (null bei Erfolg)
`message`	String	Lesbare Nachricht

Fehlerantworten¶

HTTP-Status	Bedeutung
`400`	Ungültige Anfrage (fehlende oder falsche Parameter)
`401`	Nicht authentifiziert (Token fehlt oder ungültig)
`403`	Keine Berechtigung (Rolle unzureichend oder Ressource gehört anderem Kunden)
`404`	Ressource nicht gefunden
`409`	Konflikt (z. B. Duplikat)
`422`	Validierungsfehler
`429`	Zu viele Anfragen (Rate-Limit überschritten)
`500`	Interner Serverfehler

Beispiel-Fehlerantwort:

{
  "data": null,
  "error": "not authenticated",
  "message": "Authentication required"
}

Brute-Force-Schutz¶

Das Panel schützt Login und Passwort-Reset gegen automatisierte Angriffe durch einen kumulativen Fehlversuchs-Zähler pro IP (kein gleitendes Fenster pro Minute).

Endpunkt	Verhalten
Login (`/auth/login`)	Nach 5 Fehlversuchen in 15 Minuten wird die IP für 15 Minuten gesperrt
Passwort-Reset (`/auth/forgot-password`)	Dieselbe Zählung greift — ein Reset-Versuch zählt als Fehlversuch für die IP

Schwellenwerte sind unter Einstellungen > Sicherheit > Login-Schutz konfigurierbar (login_max_attempts, login_lockout_minutes).

Bei Sperrung antwortet die API mit HTTP-Status 429:

{
  "data":    { "remaining_seconds": 812 },
  "error":   "too_many_attempts",
  "message": "Zu viele Fehlversuche. Bitte in 14 Minuten erneut versuchen."
}

Kein generelles Rate-Limit

Für authentifizierte Endpunkte (Bearer-Token / X-API-Key) gibt es derzeit kein zusätzliches Request-Rate-Limit. Abuse wird über fail2ban auf Transport- Ebene und die Brute-Force-Sperre auf Login-Ebene abgefangen.

Abonnement-Kontext¶

Kunden-Endpunkte erfordern den Kontext eines Abonnements. Übergeben Sie die Abonnement-ID als Query-Parameter:

GET /api/v1/sites?subscription_id=5
Authorization: Bearer <token>

Falls der Parameter fehlt und der Kunde mehrere Abonnements hat, wird das Standard-Abonnement verwendet.

Beispiele¶

cURL¶

# Login
TOKEN=$(curl -s -X POST https://panel.beispiel.de:3443/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"kunde@beispiel.de","password":"geheim"}' \
  | jq -r '.data.token')

# Websites auflisten
curl -s https://panel.beispiel.de:3443/api/v1/sites?subscription_id=1 \
  -H "Authorization: Bearer $TOKEN" | jq

# Mit API-Schlüssel
curl -s https://panel.beispiel.de:3443/api/v1/sites?subscription_id=1 \
  -H "Authorization: Bearer ncp_a1b2c3d4..." | jq

Python¶

import requests

BASE_URL = "https://panel.beispiel.de:3443/api/v1"

# Login
resp = requests.post(f"{BASE_URL}/auth/login", json={
    "email": "kunde@beispiel.de",
    "password": "geheim"
})
token = resp.json()["data"]["token"]

headers = {"Authorization": f"Bearer {token}"}

# Websites auflisten
sites = requests.get(f"{BASE_URL}/sites",
    headers=headers,
    params={"subscription_id": 1}
)
print(sites.json())

PHP¶

<?php
$baseUrl = 'https://panel.beispiel.de:3443/api/v1';
$apiKey  = 'ncp_a1b2c3d4...';

$ch = curl_init("$baseUrl/sites?subscription_id=1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);