Authentifizierung
Zugang zur Partner-API mit API-Key (Bearer) oder OAuth2 client_credentials.
Jeder API-Aufruf muss authentifiziert sein. Es gibt zwei Wege:
1. API-Key (Bearer)
Ein API-Key wird als Bearer-Token im Authorization-Header mitgeschickt:
curl https://api.sandbox.example/v1/events \
-H "Authorization: Bearer pc_test_DEIN_SCHLUESSEL"Es gibt zwei Praefixe:
| Praefix | Umgebung | Hinweis |
|---|---|---|
pc_live_ | Produktion | Echter Mandant, echte Daten |
pc_test_ | Sandbox (staging) | Test-Mandant „Musterpartei", naechtlich zurueckgesetzt |
In der Sandbox sind nur pc_test_-Keys gueltig. Ein pc_live_-Key wird dort
abgelehnt — und umgekehrt. Keys niemals in Client-Code, Repositories oder Logs ablegen.
2. OAuth2 client_credentials
Fuer Server-zu-Server-Integrationen und Partner-Apps gibt es den OAuth-2.0-Flow
client_credentials ueber das SSO. Zuerst ein Access-Token holen:
curl https://sso.sandbox.example/oauth2/token \
-d grant_type=client_credentials \
-d client_id=DEINE_CLIENT_ID \
-d client_secret=DEIN_CLIENT_SECRET \
-d scope="read:events read:locations"Dann das Token wie einen Bearer-Key verwenden:
curl https://api.sandbox.example/v1/events \
-H "Authorization: Bearer <access_token>"Vier Ebenen der Maschinen-Zugaenge
Maschinen-Zugaenge sind in vier Ebenen gestaffelt (ADR-0104) — von einem persoenlichen Key mit den Rechten der Person bis zu einem Dienstkonto mit eigenem, knotengebundenem Rechte-Satz. Welche Scopes ein Zugang tatsaechlich hat, bestimmt die vergebende Stelle; die Scope-Hierarchie steht unter Scopes & Ebenen.
Ein Schlüssel kann alles, was die API kann, begrenzt durch seine Scopes — mit festen Ausnahmen (Rechte- und Kontoverwaltung nie), Art.-9-Scopes nur ausdrücklich, zweitem Faktor beim Anlegen, Erweitern und Rotieren und eigenem Rate-Limit je Schlüssel: API-Schlüssel – Umfang & Regeln.
Abhaengigkeit: Die konkrete Ausgabe und Verwaltung der Keys/Clients liefert ISSUE-0103 (API-Keys und Maschinen-Zugaenge, in Arbeit). Bis dahin beschreibt diese Seite den dokumentierten Vertrag.
Fehler bei der Authentifizierung
Ohne gueltigen Zugang antwortet die API mit 401 als Problem Details:
{
"type": "https://docs.example/errors/UNAUTHORIZED",
"title": "Kein oder ungueltiger Zugang",
"status": 401,
"code": "UNAUTHORIZED"
}Mehr dazu: Fehlerformat.