API-Schlüssel – Umfang & Regeln

Was ein API-Schlüssel darf (voller Umfang per Scope), welche Rechte nie gehen, Art.-9-Daten, zweiter Faktor und Rate-Limits je Schlüssel.

Ein API-Schlüssel kann alles, was die interne API kann — begrenzt durch die Scopes, die beim Anlegen vergeben wurden. Es gibt keine gesonderte Liste „für Schlüssel freigegebener“ Endpunkte: Jeder Endpunkt verlangt einen Scope, und ein Schlüssel darf ihn aufrufen, wenn sein Scope-Set den geforderten Scope abdeckt (Entscheidung E-16-AL02, ADR-0104).

Die Partner-Referenz in diesem Portal zeigt die ausdrücklich für Partner dokumentierten Endpunkte. Das ist eine Frage der Dokumentation, keine Zugriffsgrenze: Welche Endpunkte ein Schlüssel erreicht, bestimmen allein seine Scopes.

Wie die Rechte eines Schlüssels entstehen

Nie mehr als der Träger. Ein persönlicher Schlüssel wirkt mit der Schnittmenge aus den Rechten der Person und den Scopes des Schlüssels; ein Gliederungs-Schlüssel (Dienstkonto) mit der Schnittmenge aus den Rechten des Dienstkontos und seinen Scopes. Verliert die Person ein Recht, verliert es der Schlüssel im selben Moment.
Knotengebunden. Rechte gelten an einer Gliederung und ihren Untergliederungen — nie an übergeordneten oder benachbarten Gliederungen.
Öffentliche Schlüssel (Websites, Widgets) tragen nur view-Scopes und sind an Origins bzw. eine IP-Allowlist gebunden.

Was über Schlüssel nie geht

Bereich	Beispiele	Grund
Verwaltungs-Scopes	`manage:…`, `assign:…`	zu breit; Rechtevergabe bleibt beim Menschen
Rechte- und Kontoverwaltung	Berechtigungen, Rollenvorlagen, Konten, Passwort, zweiter Faktor, Sitzungen, API-Schlüssel selbst	Schutz vor Eskalation und Kontoübernahme
Self-Service-Endpunkte ohne Scope	eigenes Konto, eigene Datenschutz-Anträge, Push-Abos	dort wirkt keine Scope-Grenze — Antwort `403 AUTHZ_API_KEY_SCOPE_REQUIRED`

Sensible Daten (Art. 9 DSGVO und Finanzdaten)

Scopes auf besondere Kategorien personenbezogener Daten — etwa Mitglieder, Mitgliedschaften, Arbeitsgruppen, Formular-Einsendungen, Teilnahmen, Spenden mit Personenbezug — und auf Finanzdaten gibt es nur ausdrücklich:

Sie werden einzeln gewählt; eine Sammelauswahl („alle einer Gruppe“) wählt sie nie mit.
Jeder sensible Scope wird beim Anlegen bzw. Erweitern einzeln bestätigt. Die API erzwingt das: Anfragen ohne Bestätigung lehnt sie mit 422 API_KEY_SENSITIVE_SCOPE_UNCONFIRMED ab (details.unconfirmed nennt die Scopes).
Jeder Zugriff auf diese Daten wird protokolliert; Lesezugriffe sind fail-closed (ohne Protokolleintrag keine Antwort).

POST /v1/me/api-keys (Auszug)

{
  "kind": "personal",
  "label": "Mitglieder-Auswertung Musterkreis",
  "scopes": ["read:member", "read:event"],
  "confirmedSensitiveScopes": ["read:member"]
}

Zweiter Faktor

Ein frischer zweiter Faktor (SSO-Anmeldung mit TOTP bzw. Backup-Code, Nachweis im Header X-Second-Factor) ist nötig für:

das Anlegen jedes Schlüssels — schreibende und sensible Scopes sind damit immer durch den zweiten Faktor gedeckt,
jede Erweiterung (neuer Scope, höheres Rate-Limit),
jede Rotation (es entsteht ein neuer gültiger Wert).

Verkleinern, Umbenennen und Widerrufen gehen ohne zweiten Faktor. Fehlt er, antwortet die API mit 403 API_KEY_SECOND_FACTOR_REQUIRED.

Rate-Limit je Schlüssel

Zusätzlich zu den gestuften Grenzen kann jeder Schlüssel ein eigenes Limit tragen — Anfragen je Minute und je Kalendertag (UTC). Es wird beim Anlegen oder Bearbeiten gesetzt (rateLimit: { "perMinute": 60, "perDay": 10000 }) und darf den Wert des Mandanten nicht übersteigen (sonst 422 API_KEY_RATE_LIMIT_OUT_OF_RANGE). Leer bzw. null bedeutet: Wert des Mandanten. Bei Überschreitung antwortet die API mit 429 API_KEY_RATE_LIMITED und Retry-After.

Bearbeiten, Rotieren, Widerrufen

Aktion	Endpunkt (persönlich)	Endpunkt (Gliederung)
Bearbeiten (Bezeichnung, Scopes, Limit)	`PATCH /v1/me/api-keys/{id}`	`PATCH /v1/api-keys/{id}`
Rotieren mit Überlappung	`POST /v1/me/api-keys/{id}/rotate`	`POST /v1/api-keys/{id}/rotate`
Sofort widerrufen	`POST /v1/me/api-keys/{id}/revoke`	`DELETE /v1/api-keys/{id}`

Persönliche Schlüssel sieht und verwaltet nur ihre Besitzer-Person; Gliederungs-Schlüssel nur, wer manage:api-key an der Gliederung des Schlüssels hält.

Der Schlüsselwert wird nur einmal angezeigt (beim Anlegen bzw. Rotieren). Schlüssel niemals in Client-Code, Repositories oder Logs ablegen — die Präfixe pc_live_/pc_test_ werden vom Secret-Scanning erkannt.

API-Schlüssel – Umfang & Regeln

Wie die Rechte eines Schlüssels entstehenCopy Anchor Link

Was über Schlüssel nie gehtCopy Anchor Link

Sensible Daten (Art. 9 DSGVO und Finanzdaten)Copy Anchor Link

Zweiter FaktorCopy Anchor Link

Rate-Limit je SchlüsselCopy Anchor Link