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

> Automate Netcup servers via the new SCP OpenAPI v1 (Keycloak OAuth2 offline token) and issue Let's Encrypt wildcard SSL via CCP DNS-01 (acme.sh & Traefik).

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

## Key Findings (TL;DR)
- Netcup separates compute and domain automation: the SCP OpenAPI 3.1 REST API v1 (Keycloak OAuth2 Bearer tokens) manages KVM servers, snapshots, firewall & rDNS, while CCP offers both the modern OpenAPI 3.1 netcup API (https://api.netcup.com for CloudDNS & domains via CCP API Keys) and the Legacy API (endpoint.php?JSON via Legacy API Key + Password for classic ACME plugins).
- Legacy SCP SOAP webservice endpoints are retired — obtain a long-lived offline_access refresh token once via Keycloak's OAuth2 Device Flow (client_id=scp) for headless cron scripts and CI/CD pipelines.
- When automating Let's Encrypt DNS-01 wildcard certificates (acme.sh dns_netcup, Lego, or Traefik), always set a 600–900 second propagation wait because Netcup authoritative nameservers batch zone reloads every ~5–10 minutes.
- Combine nightly SCP snapshot rotation (€0 storage surcharge within free disk headroom; online CoW on x86 RS/VPS, offline VM-stopped on ARM64 G12.5) with automated IPv4/IPv6 PTR updates for reproducible infrastructure-as-code.

## Execution Checklist
1. **Request an SCP OAuth2 Offline Refresh Token via Device Flow**: Call Keycloak's /auth/device endpoint with client_id=scp and scope='openid offline_access', approve the verification URL once in your browser, and store the returned refresh_token in /etc/netcup-scp.env (chmod 600).
2. **Exchange Refresh Token for Short-Lived Bearer Token in Cron**: POST grant_type=refresh_token to /realms/scp/protocol/openid-connect/token before calling lowercase /scp-core/api/v1/servers endpoints (ensuring your caller IP matches any SCP IP/CIDR allowlist) for snapshots or rDNS updates.
3. **Generate CCP API Keys or Legacy DNS Credentials for ACME Wildcard TLS**: In CCP -> Master Data -> API, generate API Keys for https://api.netcup.com (CloudDNS & domains) or a Legacy API Key + Legacy API Password for endpoint.php?JSON ACME clients like acme.sh (dns_netcup --dnssleep 600) and Traefik (NETCUP_PROPAGATION_TIMEOUT=900).

---

One of the most common points of confusion when automating Netcup infrastructure in 2026 is mixing up **SCP** and **CCP** credentials—or following outdated blog tutorials that reference retired SOAP endpoints. Netcup strictly separates compute management from billing and domain DNS:

| Plane & Portal | API Endpoint Base | Authentication Method | What You Automate Here |
| :--- | :--- | :--- | :--- |
| **SCP (Server Control Panel)** | `https://www.servercontrolpanel.de/scp-core/api/v1` (OpenAPI 3.1) | **Keycloak OAuth2** (`client_id=scp`, `offline_access` Refresh Token → `Bearer` JWT; optional IP/CIDR allowlist) | List/boot/reboot KVM servers, **€0 Snapshots** (online CoW on x86; offline on ARM64), SCP Firewall policies, **IPv4/IPv6 PTR (rDNS)**, Rescue ISO |
| **CCP — New `netcup API`** | `https://api.netcup.com` (OpenAPI 3.1 REST) | **CCP API Key** (`CCP → Master Data → API`) | Modern REST automation for **CloudDNS** zones and domain management |
| **CCP — `Legacy API`** | `https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON` | **Legacy JSON/SOAP Session** (`customernumber` + Legacy `apikey` + Legacy `apipassword`) | Classic **ACME DNS-01 wildcard SSL** plugins (`acme.sh`, Traefik/Lego, Certbot, `netcup-dns` Terraform provider) |

## 1. Authenticating to the New SCP REST API v1 (Headless Device Flow)

Because SCP accounts support hardware 2FA/TOTP, static passwords cannot be posted directly to REST endpoints. Instead, run a one-time **OAuth2 Device Authorization Flow** from your workstation or server terminal to obtain a persistent `offline_access` refresh token:

```bash
# Step 1: Start OAuth2 Device Code request (request 'offline_access' so cron jobs never need a browser!)
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 '"Open in browser: \(.verification_uri_complete)\nUser Code: \(.user_code)"'
DEVICE_CODE=$(echo "$DEVICE_RESP" | jq -r '.device_code')

# Step 2: After approving the login + 2FA in your browser, exchange device_code for your offline refresh_token
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
```

> **SCP OpenAPI 3.1 Operational Rules:** Inspect every request schema at `https://www.servercontrolpanel.de/scp-core/api/v1/openapi` (and MCP specification at `https://www.servercontrolpanel.de/scp-core/api/v1/openapi/mcp`, or Swagger UI in **SCP → Account → API**). Note two strict enforcement rules: (1) all SCP REST URL paths and query parameters are **case-sensitive lowercase**, and (2) if you configure an **IP / CIDR allowlist** in your SCP user API settings, requests from non-allowlisted IPs will be blocked even with a valid Bearer token.

## 2. Automated Pre-Upgrade / Nightly CoW Snapshot Rotation Script

Netcup x86 G12.5 Root-Servers and VPS tiers include **€0 live online Copy-on-Write (CoW) snapshots** inside SCP (as long as free disk blocks exist on the host volume; note that **ARM64 G12.5 VPS (`VPS 500–8000 ARM G12.5`) supports Offline Snapshots only**, requiring the VM to be stopped first). Drop this script into `/usr/local/sbin/netcup-auto-snapshot.sh` to mint a fresh Bearer token, resolve your server ID, create a timestamped snapshot before `apt unattended-upgrades`, and prune older automated snapshots:

```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. Mint short-lived Bearer access_token from offline refresh_token
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. Resolve numeric server ID by hostname or vServer name (e.g. v2202611...)
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. Create an online Copy-on-Write snapshot (on ARM64 G12.5, stop VM first & set "onlineSnapshot":false)
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\":\"Automated pre-upgrade CoW snapshot\",\"onlineSnapshot\":true}"

echo "Created SCP snapshot ${SNAP_NAME} on server ${SERVER_ID}"

# 4. Prune older automated snapshots (keep the 2 newest 'auto-*' snapshots)
curl -fsS -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "${API_BASE}/servers/${SERVER_ID}/snapshots" \
  | jq -r '[.[] | select(.name | startswith("auto-"))] | sort_by(.name) | reverse | .[2:][].name' \
  | while read -r OLD_SNAP; do
      [ -n "${OLD_SNAP}" ] || continue
      curl -fsS -X DELETE -H "Authorization: Bearer ${ACCESS_TOKEN}" \
        "${API_BASE}/servers/${SERVER_ID}/snapshots/${OLD_SNAP}"
      echo "Pruned old SCP snapshot ${OLD_SNAP}"
    done
```

You can also automate **IPv4 and `/64` IPv6 reverse DNS (PTR)** for mail servers (see our [Port 25 & rDNS Mail Guide](/guides/netcup-port-25-mail-server-rdns-guide/)) via `POST ${API_BASE}/rdns/ipv4` and `POST ${API_BASE}/rdns/ipv6` with `{"ip": "203.0.113.42", "rdns": "mail.example.com"}`.

## 3. Wildcard Let's Encrypt SSL via CCP DNS-01 (`acme.sh` & Traefik v3)

If your domains use Netcup's free authoritative nameservers (`root-dns.netcup.net`, `second-dns.netcup.net`, `third-dns.netcup.net` — included with [Webhosting 2000–8000](/webhosting/) and domain registrations), open **CCP (`customercontrolpanel.de`) → Master Data (`Stammdaten`) → API**. There you will find two credential sections: **API Keys** for the modern OpenAPI 3.1 `netcup API` (`https://api.netcup.com` for custom CloudDNS & domain automation), and **Legacy API** credentials (`Legacy API Key` + `Legacy API Password` for `https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON`), which existing third-party ACME clients (`acme.sh` `dns_netcup` and Traefik/Lego) use below.

### Option A: `acme.sh` Wildcard Certificate (`--dnssleep 600` Fix)

Because Netcup reloads DNS zones on a `~5–10 minute` batch cycle, skipping `--dnssleep` causes Let's Encrypt to query stale `TXT` records and fail. Setting `600` seconds achieves 100% reliable renewals:

```bash
export NC_Apikey="YOUR_CCP_API_KEY"
export NC_Apipw="YOUR_CCP_API_PASSWORD"
export NC_CID="YOUR_NUMERIC_CUSTOMER_ID"

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

### Option B: Traefik v3 / Coolify Docker Compose Labels

When running [Coolify or Dokploy](/guides/coolify-dokploy-self-hosting-netcup-guide/) behind Traefik v3, configure the built-in `netcup` Lego provider with explicit propagation timeouts so internal VPN-only dashboards (`*.internal.example.com` behind WireGuard) get valid TLS certificates without exposing port `80`:

```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=ops@example.com"
      - "--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. Terraform / OpenTofu Ecosystem Reality Check

If you manage multi-cloud GitOps state in Terraform or OpenTofu:
- **DNS Zones (`CCP`):** Community providers (`registry.terraform.io` `netcup-dns`) manage `A`, `AAAA`, `CAA`, `MX`, `SPF`, and `DKIM` records against the CCP `Legacy API` (`endpoint.php?JSON`), while custom REST integrations and CloudDNS workflows can target the new OpenAPI 3.1 `netcup API` (`https://api.netcup.com`).
- **Compute Ordering vs. Day-2 Ops:** Unlike [Hetzner Cloud's hourly `hcloud_server` resource](/compare/netcup-vs-hetzner/), Netcup does not expose a public-cloud Terraform create/destroy provisioning API: server contracts are ordered via cart/CCP on `1M`, `12M`, or `24M` billing terms (with optional hourly billing documented in the Help Center for x86 VPS, and a 1-month-to-month-end notice rule under AGB § 6 — check our [1-month CCP cancellation calculator](/tools/cancellation-calculator/)), while **Day-2 configuration** (SSH keys, firewall rules, cloud-init rebuilds, snapshots, and Ansible inventory discovery) is automated cleanly through the **SCP REST API v1**.

## Frequently Asked Questions

### Why did my old Netcup SCP SOAP script stop working?

Netcup migrated the Server Control Panel (servercontrolpanel.de) from the legacy SOAP webservice to a RESTful OpenAPI 3.1 architecture (documented at /scp-core/api/v1/openapi and /scp-core/api/v1/openapi/mcp) secured by Keycloak OpenID Connect (OAuth2). All server lifecycle, snapshot, rescue, firewall, and rDNS operations now run against https://www.servercontrolpanel.de/scp-core/api/v1 using Bearer access tokens.

### Can I use my SCP OAuth2 token to edit Netcup domain DNS records for Let's Encrypt?

No. Domain registration and DNS zones live in the Customer Control Panel (CCP: customercontrolpanel.de), which offers two APIs under Master Data -> API: (1) the new OpenAPI 3.1 netcup API at https://api.netcup.com for CloudDNS and domains using CCP API Keys, and (2) the Legacy API at https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON using customernumber, Legacy API Key, and Legacy API Password (still used by classic acme.sh and Traefik/Lego DNS-01 plugins).

### Why does Traefik or acme.sh fail with NXDOMAIN on Netcup DNS-01 challenges?

Netcup's authoritative DNS cluster batches zone file reloads roughly every 5 to 10 minutes rather than instant sub-second push. Set --dnssleep 600 in acme.sh or NETCUP_PROPAGATION_TIMEOUT=900 (and NETCUP_POLLING_INTERVAL=30) in Traefik/Lego so ACME validation waits for zone propagation.

### Does an SCP offline_access refresh token expire if my cron job runs weekly?

Standard Keycloak offline tokens (requested with scope='openid offline_access') survive server reboots and remain valid as long as they are refreshed at least once every 30 days—and you can revoke them anytime inside SCP account security settings.

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