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