Zum Hauptinhalt springen
SSH-Labor & Gutscheinpool
EU EUServerLab
RATGEBER Stand: · 10 Min. Lesezeit

Netcup SCP REST-API (OAuth2) & CCP DNS-01 Automatisierung: Snapshots, rDNS & Wildcard-SSL (2026)

Netcup Server per neuer SCP OpenAPI v1 (Keycloak OAuth2 Token) automatisieren und Let's Encrypt Wildcard-Zertifikate per CCP DNS-01 (acme.sh & Traefik) lösen.

Autor: Hai Liu (Systems & Cloud TCO Engineer) · * Mit Sternchen/Partnerlink markierte Links (rel="sponsored") unterstützen unser Testlabor ohne Mehrkosten für Sie.

Kurzüberblick

Stand: 2026-11-22

Kurz-Checkliste zur Umsetzung

  1. 1
    Einmalig OAuth2 Offline-Refresh-Token per Device-Flow abrufen

    Keycloak-Endpunkt /auth/device mit client_id=scp und scope='openid offline_access' aufrufen, Login inkl. 2FA im Browser bestätigen und refresh_token in /etc/netcup-scp.env (chmod 600) sichern.

  2. 2
    Im Cronjob kurzlebiges Bearer-Token tauschen & Snapshot auslösen

    Per grant_type=refresh_token ein frisches access_token abrufen und mit onlineSnapshot:true gegen /scp-core/api/v1/servers/{id}/snapshots senden.

  3. 3
    CCP DNS-API-Zugangsdaten für Wildcard-SSL hinterlegen

    Im CCP unter Stammdaten -> API Schlüssel erzeugen (neue netcup API für CloudDNS bzw. Legacy-API-Key + Passwort für klassische CCP-DNS-Clients wie acme.sh --dnssleep 600 oder Traefik v3 mit NETCUP_PROPAGATION_TIMEOUT=900).

Wer Netcup-Infrastruktur automatisiert, stolpert in älteren Forenbeiträgen häufig über abgeschaltete SOAP-URLs oder verwechselt die Zugangsdaten der getrennten Verwaltungsportale. In der aktuellen Architektur gilt diese klare Aufgabenteilung:

Portal & EbeneOffizieller API-EndpunktAuthentifizierungAutomatisierbare Funktionen
SCP (Server Control Panel)https://www.servercontrolpanel.de/scp-core/api/v1Keycloak OAuth2 (client_id=scp, offline_access → Bearer-JWT + IP/CIDR-Allowlist)KVM-Status, 0-€-Snapshots (Online-CoW auf BIOS-x86; Offline auf ARM64/UEFI), SCP-Firewall, IPv4/IPv6-rDNS (PTR), Rescue & ISO
CCP – Neue netcup API (OAS 3.1)https://api.netcup.comAPI-Key (Bearer-Auth, unter CCP → Stammdaten → API)Moderne OpenAPI-3.1-REST-Steuerung für CloudDNS & Domain-Verwaltung
CCP – Legacy APIhttps://ccp.netcup.net/run/webservice/servers/endpoint.php?JSONJSON/SOAP-Session (customernumber + Legacy-apikey + Legacy-apipassword)Klassische CCP-DNS-Zonen (A, AAAA, TXT, CAA) & ACME DNS-01 (acme.sh dns_netcup, Traefik, Lego)
PANEL-ÜBERSICHT & EINSTELLUNGEN AS197540 · SCP
Server Control Panel (SCP) – RS 1000 G12.5 Steuerung
servercontrolpanel.de · KVM-Konsole · Eigenes ISO · 0 € CoW-Snapshots · Firewall
💿 Medien / Eigenes ISO
Proxmox VE / Debian 12 / eigenes Rettungs-ISO mounten
📸 Snapshots (CoW)
0,00 € inkl. MwSt. Copy-on-Write Sofort-Backup
🔓 SCP → Firewall
„netcup Mail block“ löschen → Port 25/465/587 sofort frei
🌐 Netzwerk & rDNS
2,5 Gbit/s EU/US Fair-Use · IPv4 + IPv6 /64 PTR
Die SCP REST-API v1 automatisiert KVM-Steuerung, kostenlose Copy-on-Write-Snapshots, Firewall-Profile und Dual-Stack-rDNS

1. SCP REST-API v1: Headless-Login per OAuth2 Device-Flow

Da moderne SCP-Konten mit 2FA/TOTP geschützt sind, werden keine Klartext-Passwörter im Skript gespeichert. Stattdessen erzeugen Sie einmalig über den Keycloak Device-Authorization-Flow ein langlebiges offline_access-Token:

# Schritt 1: Device-Code mit 'offline_access' anfordern (wichtig für unbeaufsichtigte Cronjobs!)
DEVICE_RESP=$(curl -sS -X POST \
  "https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/auth/device" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=scp" \
  -d "scope=openid offline_access")

echo "$DEVICE_RESP" | jq -r '"Im Browser öffnen: \(.verification_uri_complete)\nCode: \(.user_code)"'
DEVICE_CODE=$(echo "$DEVICE_RESP" | jq -r '.device_code')

# Schritt 2: Nach Browser-Freigabe das dauerhafte refresh_token abrufen und geschützt ablegen
TOKEN_RESP=$(curl -sS -X POST \
  "https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "client_id=scp" \
  -d "device_code=${DEVICE_CODE}")

REFRESH_TOKEN=$(echo "$TOKEN_RESP" | jq -r '.refresh_token')
sudo install -m 600 /dev/null /etc/netcup-scp.env
echo "SCP_REFRESH_TOKEN=${REFRESH_TOKEN}" | sudo tee /etc/netcup-scp.env >/dev/null

OpenAPI-3.1- & MCP-Referenz: Die SCP REST-API folgt dem OpenAPI-3.1-Standard (dokumentiert unter https://www.servercontrolpanel.de/scp-core/api/v1/openapi sowie als MCP-Schema unter https://www.servercontrolpanel.de/scp-core/api/v1/openapi/mcp). Alle URL-Pfade sind strikt kleingeschrieben (case-sensitive lowercase), und in den SCP-Benutzereinstellungen (Account → API) lässt sich eine IP-/CIDR-Allowlist pflegen – prüfen Sie diese Freigabeliste zuerst, falls Requests von einem neuen Runner abgewiesen werden.

2. Automatische CoW-Snapshots vor Kernel- & Docker-Updates

G12.5 x86-Root-Server und x86-VPS im BIOS-Bootmodus unterstützen im SCP kostenlose lokale Online-Copy-on-Write-Snapshots (0,00 €) im laufenden Betrieb, solange freier Plattenplatz im Volume vorhanden ist. Wichtige Ausnahme: Alle ARM64-VPS G12.5 (sowie UEFI-gebootete VMs) erlauben technisch ausschließlich Offline-Snapshots – die VM muss vor dem Snapshot heruntergefahren werden ("onlineSnapshot": false samt "diskName"). Das folgende Bash-Skript holt ein kurzlebiges Bearer-Token und legt auf einem BIOS-x86-Server vor nächtlichen Wartungsarbeiten automatisch einen Online-Sicherungspunkt an:

#!/usr/bin/env bash
set -euo pipefail
source /etc/netcup-scp.env

API_BASE="https://www.servercontrolpanel.de/scp-core/api/v1"
TOKEN_URL="https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token"

# 1. Kurzlebiges Access-Token per Refresh-Token abrufen
ACCESS_TOKEN=$(curl -fsS -X POST "$TOKEN_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=scp" \
  -d "refresh_token=${SCP_REFRESH_TOKEN}" | jq -r '.access_token')

# 2. Eigene Server-ID ermitteln
SERVER_ID=$(curl -fsS -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "${API_BASE}/servers" | jq -r '.[0].id')

SNAP_NAME="auto-$(date -u +%Y%m%d-%H%M)"

# 3. Online-CoW-Snapshot im laufenden Betrieb erstellen (BIOS-x86; für ARM64/UEFI VM vorher stoppen & onlineSnapshot:false + diskName nutzen)
curl -fsS -X POST "${API_BASE}/servers/${SERVER_ID}/snapshots" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"${SNAP_NAME}\",\"description\":\"Automatischer Pre-Update CoW-Snapshot\",\"onlineSnapshot\":true}"

echo "SCP-Snapshot ${SNAP_NAME} für Server ${SERVER_ID} angelegt."

Ebenso lassen sich IPv4- und /64-IPv6-PTR-Einträge (rDNS) für eigene Mailserver (siehe Port-25- & Mailcow-Guide) automatisiert über ${API_BASE}/rdns/ipv4 und ${API_BASE}/rdns/ipv6 setzen.

3. Wildcard-SSL per CCP DNS-01 (acme.sh & Traefik v3)

Nutzen Ihre Domains (z. B. inklusive der Gratis-.de-Domains in NUE bzw. internationalen Inklusivdomains beim Netcup Webhosting) die kostenlosen Netcup-Nameserver, finden Sie im CCP (customercontrolpanel.de) → Stammdaten → API zwei getrennte API-Optionen: Für CloudDNS und moderne REST-Integrationen steht die neue OpenAPI-3.1-basierte netcup API (https://api.netcup.com) per Bearer-API-Key bereit; für klassische CCP-DNS-Zonen in bestehenden Clients wie acme.sh (dns_netcup), Traefik und Lego erzeugen Sie dort einen Legacy-API-Key samt Legacy-API-Passwort für https://ccp.netcup.net/run/webservice/servers/endpoint.php.

Variante A: acme.sh mit --dnssleep 600 (ohne Timeout-Fehler)

Da Netcup-Nameserver geänderte Zonendateien gebündelt alle ca. 5 bis 10 Minuten ausrollen, führt eine sofortige Let’s-Encrypt-Abfrage zu NXDOMAIN. Mit 600 Sekunden Wartezeit läuft jede Verlängerung stabil durch:

export NC_Apikey="IHR_CCP_API_KEY"
export NC_Apipw="IHR_CCP_API_PASSWORT"
export NC_CID="IHRE_KUNDENNUMMER"

acme.sh --issue --dns dns_netcup \
  --dnssleep 600 \
  -d example.de -d '*.example.de' \
  --keylength ec-256

Variante B: Traefik v3 / Coolify Reverse-Proxy (Auch für interne VPN-Hosts)

Für Coolify- oder Dokploy-Setups hinter WireGuard stellt Traefik per DNS-01 gültige Zertifikate aus, ohne Port 80 öffentlich öffnen zu müssen:

services:
  traefik:
    image: traefik:v3.2
    command:
      - "--certificatesresolvers.le-netcup.acme.dnschallenge=true"
      - "--certificatesresolvers.le-netcup.acme.dnschallenge.provider=netcup"
      - "--certificatesresolvers.le-netcup.acme.dnschallenge.delaybeforecheck=600"
      - "--certificatesresolvers.le-netcup.acme.dnschallenge.resolvers=46.38.225.230:53,1.1.1.1:53"
      - "--certificatesresolvers.le-netcup.acme.email=admin@example.de"
      - "--certificatesresolvers.le-netcup.acme.storage=/letsencrypt/acme.json"
    environment:
      NETCUP_CUSTOMER_NUMBER: "${NC_CID}"
      NETCUP_API_KEY: "${NC_Apikey}"
      NETCUP_API_PASSWORD: "${NC_Apipw}"
      NETCUP_PROPAGATION_TIMEOUT: "900"
      NETCUP_POLLING_INTERVAL: "30"

4. Einordnung für Terraform & OpenTofu

Live-Pool Edge-Cache · Klick löst direkt im Warenkorb ein
Tarif-Gutschein wählen:
#rs1

RS 1000 G12.5

2 Monate gratis · Auch für Bestandskunden (12 Mon. Laufzeit)

EPYC 9645/9655 Zen 5 4 dedizierte Kerne 8 GB DDR5 ECC 128 GB NVMe · 2,5 Gbit/s
★ Rabatt-Vergleich vs. 5,95 € Neukunden-Code (#5e)
Mit #rs1 sparen Sie im 1. Jahr 43,46 € inkl. MwSt. statt 5,95 € mit dem Neukunden-Code #5e – genau 37,51 € mehr Ersparnis (auch als Bestandskunde).
Ziehe Zufallscode (1 aus 5)... 1/5 Gutschein jetzt direkt anwenden * →
* Partnerlink (Werbung, ohne Mehrkosten)
Automatische Warenkorb-Einlösung (?gutschein=) · Produkt-Codes gelten auch für Bestandskunden. Vollständige Einlöse-Regeln →

Häufige Fragen zum Thema (FAQ)

Warum funktionieren alte Netcup-SCP-SOAP-Skripte nicht mehr? ▼

Netcup hat das Server Control Panel (servercontrolpanel.de) vollständig auf eine moderne OpenAPI-3.1-REST-Schnittstelle mit Keycloak-OAuth2-Authentifizierung umgestellt. Alle Aktionen für Start/Stopp, Snapshots, Firewall und rDNS laufen über https://www.servercontrolpanel.de/scp-core/api/v1 per Bearer-JWT.

Kann ich mit dem SCP-OAuth2-Token auch DNS-TXT-Einträge für Let's Encrypt setzen? ▼

Nein. Domains und DNS-Zonen liegen im Customer Control Panel (CCP: customercontrolpanel.de). Dort bietet Netcup unter Stammdaten -> API zwei offizielle Schnittstellen: die moderne OpenAPI-3.1-basierte netcup API (https://api.netcup.com per Bearer-API-Key für CloudDNS & Domains) sowie die Legacy API (https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON mit Kundennummer, Legacy-API-Key und Legacy-API-Passwort, die klassische ACME-Clients wie acme.sh dns_netcup und Traefik/Lego für Standard-CCP-DNS-Zonen nutzen).

Warum schlägt Traefik oder acme.sh bei Netcup DNS-01 mit NXDOMAIN fehl? ▼

Die autoritativen Netcup-Nameserver übernehmen DNS-Änderungen gebündelt alle ca. 5 bis 10 Minuten. Setzen Sie --dnssleep 600 in acme.sh bzw. NETCUP_PROPAGATION_TIMEOUT=900 in Traefik/Lego, damit die ACME-Prüfung erst nach erfolgtem Zonen-Reload startet.

Läuft das offline_access Refresh-Token im SCP bei wöchentlichen Cronjobs ab? ▼

Solange das mit scope='openid offline_access' angeforderte Refresh-Token mindestens einmal innerhalb von 30 Tagen eingelöst wird, bleibt es dauerhaft für Headless-Skripte aktiv und lässt sich im SCP jederzeit widerrufen.

Weiterführende Einzeltests & Praxis-Ratgeber

Direkte Anbieter-Vergleiche