hermes-skills/skills/devops/ops-portal-and-collector/references/netcup-scp-api.md

netcup SCP REST API Authentication

The netcup Server Control Panel (SCP) REST API uses Keycloak (OIDC) password grant for authentication, NOT the CCP API key from Master Data.

Auth Flow

TOKEN=$(curl -s "https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&client_id=scp&username=${CUSTOMER_NUMBER}&password=${CCP_PASSWORD}&scope=openid" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

Parameters

Field	Value	Source
grant_type	password	OIDC resource owner password flow
client_id	scp	Static SCP client ID
username	Customer number	e.g. 389212 from CCP Master Data page
password	CCP login password	Same as web login password
scope	openid	Returns access_token + id_token + refresh_token

Token properties

• Access token expires in 300 seconds (5 min)
• Refresh token expires in 1800 seconds (30 min)
• Always obtain a fresh token each collection cycle

API Endpoints

Base: https://www.servercontrolpanel.de/scp-core/api/v1/

Endpoint	Response
GET /servers	Array of servers with id, name, template, disabled, hostname
GET /servers/{id}	Full detail: IPv4, IPv6, architecture, disks, RAM

Known Working

• RS 2000 G12 — ID 890903, 152.53.192.33
• RS 4000 G12 — IDs 894147 (152.53.36.131), 894148 (152.53.39.202), 894149 (152.53.241.111)
• Template name format: "RS {1000|2000|4000} G12"

Pitfalls

• /scp-core/api/ NOT /scp-ui/api/ — /scp-ui/ returns HTML even with valid auth
• www subdomain IS required — servercontrolpanel.de does NOT respond
• CCP API Key is NOT for SCP — they use different auth systems
• Username is bare customer number, NOT customer#<number>. Adding customer# prefix returns invalid_grant / Invalid user credentials. The Keycloak realm expects the bare numeric ID. This was discovered Jul 10, 2026 after multiple failed auth attempts.