Skip to main content
SSH Lab & Live Vouchers
EU EUServerLab
GUIDE Updated: · 10 min read

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

By Hai Liu (Systems & Cloud TCO Engineer) · * Outbound voucher & store links (rel="sponsored") help fund our lab at zero extra cost to you.

Summary

Updated: 2026-11-22

Quick Execution Checklist

  1. 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. 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. 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 & PortalAPI Endpoint BaseAuthentication MethodWhat 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 APIhttps://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 APIhttps://ccp.netcup.net/run/webservice/servers/endpoint.php?JSONLegacy JSON/SOAP Session (customernumber + Legacy apikey + Legacy apipassword)Classic ACME DNS-01 wildcard SSL plugins (acme.sh, Traefik/Lego, Certbot, netcup-dns Terraform provider)
CONTROL PANEL REFERENCE AS197540 · SCP
Server Control Panel (SCP) — RS 1000 G12.5 Management View
servercontrolpanel.de · KVM Console · Custom ISO · €0 CoW Snapshots · Firewall
💿 Media / Custom ISO
Mount Proxmox VE / Debian 12 / Alpine (.iso)
📸 Snapshots (CoW)
€0.00 Free Copy-on-Write Instant Rollback
🔓 SCP → Firewall
Delete "netcup Mail block" → Unlocks TCP 25/465/587 in 1 Click
🌐 Network & rDNS
2.5 Gbps EU/US Fair-Use · IPv4 /22 + IPv6 /64 PTR
Netcup SCP OpenAPI v1 controls KVM lifecycle, €0 Copy-on-Write snapshots, firewall rulesets, and dual-stack PTR records

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:

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

#!/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) 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 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:

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

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"
      - "[email protected]"
      - "--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:

Edge-Cached Pool · Click Code to Auto-Apply
Select Model Tier:
#rs1

RS 1000 G12.5

2 Months Free · Valid for New & Existing Customers (12M Term)

EPYC 9645/9655 Zen 5 4 Dedicated Cores 8GB DDR5 ECC 128GB NVMe · 2.5G EU/US
★ Savings Check vs. €5 Net Welcome Code (#5e)
At 0% Non-EU VAT, #rs1 saves €36.52 net vs. €5.00 net with #5e — €31.52 extra net savings.
Drawing random code (1 of 5)... 1/5 Use This Voucher Automatically * →
* Partner link (zero extra cost to you)
Auto-applies via ?gutschein= cart link · Product vouchers work for new & existing accounts. Full Voucher Rules & Pool →

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.

Related Reviews & Setup Guides

Provider Comparisons