Rechte & Scopes

Was ein Aufruf darf, ist die Schnittmenge aus den Rollen des Prinzipals, dem Scope des Schlüssels und dem Deckel der Organisation. Sie wird bei jedem Aufruf frisch berechnet.

Die Schnittmenge

Text

wirksam = Rollen des Prinzipals
        ∩ Scope des Schlüssels
        ∩ Rechte-Stand beim Anlegen des Schlüssels
        ∩ Deckel der Organisation für die API
        ∩ KI-Vollmacht (nur bei persönlichen Schlüsseln)

Ein Scope kann nur wegnehmen, nie hinzufügen. Verliert die Person eine Rolle, verliert der Schlüssel sie beim nächsten Aufruf mit.

Ressourcen-Scopes

Je Ressource: kein Zugriff, lesen oder lesen und schreiben.

Ressource	Lesen	Schreiben
Kontakte · `contacts`	contacts:read	contacts:write
Firmen · `companies`	companies:read	companies:write
Aufgaben · `tasks`	tasks:read	tasks:write
Dokumente · `documents`	documents:read	documents:write
Rechnungen · `invoices`	invoices:read	invoices:write
Zeiten · `time_entries`	time_entries:read	time_entries:write
Webhook-Endpunkte · `webhook_endpoints`	webhook_endpoints:read	webhook_endpoints:write

Familien

Folgenreiche Aktionen stehen in Familien. Jede ist gesperrt, bis du sie am Schlüssel einzeln freigibst.

Familie	Was dazugehört	Freigabe verlangt
Löschen	Datensätze löschen	IP-Regel am Schlüssel; 10/min und 300 je Tag
Geldwirksam	Buchungen und Beträge ändern	IP-Regel; Stufe der KI-Vollmacht
Belege festschreiben	Rechnungen festschreiben	IP-Regel; Stufe der KI-Vollmacht
Versenden	Rechnungen und Belege versenden	IP-Regel; Stufe der KI-Vollmacht
Geldläufe	Mahn- und Zahlungsläufe starten	IP-Regel; Stufe der KI-Vollmacht

Ist eine Familie gesperrt, antwortet die API mit 403 RISK_FAMILY_BLOCKED. Eine Rückfrage zur Bestätigung gibt es über die API nicht: was im Web oder per MCP eine Bestätigung braucht, ist hier gesperrt. Im Batch ist keine Geld-Familie erlaubt (BATCH_FAMILY_NOT_ALLOWED).

IP-Regel

Pflicht für jeden Schreib-Scope und jede freigegebene Familie; ohne IP-Regel ist ein Schlüssel höchstens lesend.
Bis zu 32 Netze in CIDR-Schreibweise, IPv4 mindestens /24, IPv6 mindestens /48.
Private Netze, Loopback und Link-Local sind nicht erlaubt.
Ein Aufruf von außerhalb endet als 401, der Inhaber bekommt höchstens einmal je Stunde eine Mail und einen Eintrag in der Glocke.

API-Stufe der Organisation

Stufe	Wirkung
aus	kein Aufruf, auch kein Lesen
lesen	nur lesende Aufrufe; schreibende enden mit 403 FORBIDDEN
an	Lesen und Schreiben nach den Scopes; verlangt die Zustimmung zu den Nutzungsbedingungen

Wie das Modul der Preview-Phase davor greift, zeigt die Matrix unter Fehler.