# 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.

- Canonical URL: https://euserverlab.com/de/guides/netcup-scp-rest-api-dns-automation-guide/
- Language: de
- Published: 2026-11-15 | Updated: 2026-11-22
- Publisher: EUServerLab (https://euserverlab.com/de/methodology/)

## Wichtigste Erkenntnisse (Kurzfassung)
- Netcup trennt API-Zugriffe strikt: Die SCP OpenAPI 3.1 REST-API v1 (Keycloak OAuth2 Bearer-Token) steuert KVM-Server, Snapshots, Firewall & rDNS; im CCP stehen für Domains & DNS sowohl die neue netcup API (https://api.netcup.com, OpenAPI 3.1 für CloudDNS & Domains per API-Key) als auch die Legacy API (endpoint.php?JSON per Legacy-API-Key + Passwort) bereit.
- Der alte SCP-SOAP-Webservice ist abgeschaltet – erzeugen Sie einmalig per OAuth2 Device-Flow (client_id=scp, scope='openid offline_access') ein Refresh-Token für Cronjobs und CI/CD-Pipelines.
- Bei Let's Encrypt Wildcard-SSL per DNS-01 (acme.sh dns_netcup, Lego oder Traefik) zwingend 600–900 Sekunden Wartezeit setzen, da Netcup-Nameserver Zonen im 5–10-Minuten-Intervall neu laden.
- Kombinieren Sie kostenlose lokale SCP-Snapshots (Online-CoW auf BIOS-x86-Servern; Offline-Snapshots auf ARM64/UEFI) vor automatischen Kernel-Updates mit skriptgesteuerten IPv4/IPv6-PTR-Einträgen.

## Schritt-für-Schritt-Checkliste
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. **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. **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 & Ebene | Offizieller API-Endpunkt | Authentifizierung | Automatisierbare Funktionen |
| :--- | :--- | :--- | :--- |
| **SCP (Server Control Panel)** | `https://www.servercontrolpanel.de/scp-core/api/v1` | **Keycloak 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.com` | **API-Key** (`Bearer`-Auth, unter `CCP → Stammdaten → API`) | Moderne OpenAPI-3.1-REST-Steuerung für **CloudDNS** & Domain-Verwaltung |
| **CCP – `Legacy API`** | `https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON` | **JSON/SOAP-Session** (`customernumber` + Legacy-`apikey` + Legacy-`apipassword`) | Klassische CCP-**DNS-Zonen** (`A`, `AAAA`, `TXT`, `CAA`) & **ACME DNS-01** (`acme.sh dns_netcup`, Traefik, Lego) |

## 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:

```bash
# 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:

```bash
#!/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](/de/guides/netcup-port-25-mail-server-rdns-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](/de/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:

```bash
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](/de/guides/coolify-dokploy-self-hosting-netcup-guide/) hinter WireGuard stellt Traefik per DNS-01 gültige Zertifikate aus, ohne Port `80` öffentlich öffnen zu müssen:

```yaml
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

- **DNS-Zonen (`CCP`):** Über den Terraform-Provider `netcup-dns` verwalten Sie `A`-, `AAAA`-, `MX`-, `SPF`- und `DKIM`-Einträge deklarativ per GitOps.
- **Server-Betrieb vs. Neubestellung:** Während [Hetzner Cloud](/de/compare/netcup-vs-hetzner/) Instanzen per Public-Cloud-API neu erzeugt und löscht, werden Netcup-Verträge im Warenkorb gebucht (1 Monat Frist zum Monatsende im [Kündigungsfrist-Rechner](/de/tools/cancellation-calculator/) prüfen) und anschließend im laufenden Betrieb vollständig über die **SCP REST-API v1** und Ansible gesteuert.

## Häufig gestellte Fragen (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.

---
Source: EUServerLab (https://euserverlab.com/de/guides/netcup-scp-rest-api-dns-automation-guide/) | Open Telemetry Dataset: https://euserverlab.com/benchmarks/vps-500-g12-5.json
