ID: DOC_000010 | Version: 0.2.1 | Status: Draft
By: Codex (GPT-5)

# Usage

## Authentifizierung
- PAM-Login: `POST /login` mit Benutzername/Passwort. Liefert JWT und setzt Session-Cookie.
- OIDC-Login: `GET /login/oidc/start` startet Flow, Callback setzt Session-Cookie.
- Alle geschuetzten Endpunkte akzeptieren `Authorization: Bearer $TOKEN` oder Session-Cookie.

### Beispiel: Login und Token nutzen
```bash
token=$(curl -s -X POST -H "Content-Type: application/json" \
  -d '{"username":"root","password":"example-password"}' \
  http://localhost/login | jq -r .token)

curl -s -H "Authorization: Bearer $token" http://localhost/me
```
Hinweis: `jq` ist optional; ohne jq das Token manuell aus der JSON-Antwort lesen.
Login ist nur fuer erlaubte Nutzer moeglich (siehe `SKD_AUTH_ALLOWED_USERS` und `SKD_AUTH_ALLOWED_GROUPS`).

## Web-UI
- Aufruf: `http://localhost/`
- Login per PAM oder OIDC (wenn konfiguriert).
- Aktionen: Benutzer sperren/entsperren, Update-Status, Update-Check, Apply/Rollback.

## API-Endpunkte (Auszug)
### Health und Identitaet
- `GET /health` (ohne Auth)
- `GET /me`

### Benutzerverwaltung
- `GET /users`
- `POST /users/{username}/disable` mit JSON `{countdown?, sound?, message?}`
- `POST /users/{username}/enable`

Beispiel (disable):
```bash
curl -X POST -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d '{"countdown":90,"sound":true,"message":"Bitte speichern"}' \
  http://localhost/users/child1/disable
```

### Update-API (lokal)
Alle Update-Endpunkte erfordern Admin-Auth.
- `GET /update/status`
- `POST /update/enroll` (optional Body: `{ "enroll_token": "..." }`)
- `POST /update/check`
- `POST /update/apply` (optional Body: `{ "version": "x.y.z" }`)
- `POST /update/rollback`
- `GET /update/logs?limit=200`

Beispiel (Enrollment):
```bash
ENROLL_TOKEN="example-enroll-token"
curl -X POST -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"enroll_token\":\"${ENROLL_TOKEN}\"}" \
  http://localhost/update/enroll
```

Beispiel (Update-Check):
```bash
curl -X POST -H "Authorization: Bearer $token" http://localhost/update/check
```
Hinweis: Ohne gespeichertes Update-Token liefert der Check einen Fehler.

## CLI-Fallback (sk.sh)
Das Legacy-Script arbeitet direkt auf dem Host und benoetigt Root-Rechte.

Aufruf:
```bash
sudo ./sk.sh USERNAME disable|enable [countdown] [sound] [countdown_time_in_seconds]
```

Beispiel:
```bash
sudo ./sk.sh demo_user disable countdown sound 90
```