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"
}

Rate-Limiting¶

Die API begrenzt die Anzahl der Anfragen pro Zeitraum, um Missbrauch zu verhindern:

Endpunkt	Limit
Login (`/auth/login`)	10 Anfragen pro Minute pro IP
Passwort-Reset	5 Anfragen pro Minute pro IP
Alle anderen Endpunkte	120 Anfragen pro Minute pro Benutzer

Bei Überschreitung des Rate-Limits antwortet die API mit HTTP-Status 429:

{
  "data": null,
  "error": "rate limit exceeded",
  "message": "Too many requests. Please try again later."
}

Rate-Limit-Header

Die API sendet folgende Header mit jeder Antwort:

Header	Beschreibung
`X-RateLimit-Limit`	Maximale Anfragen pro Zeitfenster
`X-RateLimit-Remaining`	Verbleibende Anfragen
`X-RateLimit-Reset`	Unix-Timestamp, wann das Limit zurückgesetzt wird

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);