Berechtigungen
Scopes haben die Form bereich:read bzw. bereich:write. Fehlt eine Berechtigung, antwortet die API mit 403 insufficient_scope; im Feld details.missing stehen die fehlenden Scopes. Welche Berechtigung ein Endpunkt braucht, steht in der API-Referenz bei jedem Endpunkt. Ihre aktuellen Scopes liefert GET /me.
Alle Scopes
| Bereich | Scope | Erlaubt |
|---|---|---|
| Profil und Firmendaten | profile:read | Profil, Firmen- und Rechnungsstammdaten lesen |
| Profil und Firmendaten | profile:write | Profil, Firmen- und Rechnungsstammdaten ändern |
| Kontakte | contacts:read | Kontakte (Kunden/Schuldner) lesen |
| Kontakte | contacts:write | Kontakte anlegen, ändern, löschen |
| Mandanten | clients:read | Mandanten (Inkasso/Kanzlei) lesen |
| Mandanten | clients:write | Mandanten verwalten |
| Forderungen | debts:read | Forderungen, Kosten, Zinsen, Phasen lesen |
| Forderungen | debts:write | Forderungen anlegen, ändern, Phasen wechseln, Mahnungen auslösen |
| Zahlungen und Ratenpläne | payments:read | Zahlungen und Ratenpläne lesen |
| Zahlungen und Ratenpläne | payments:write | Zahlungen erfassen, Ratenpläne verwalten |
| Briefversand | letters:read | Briefe und Zustellstatus lesen |
| Briefversand | letters:write | Briefe versenden (kostenpflichtig) |
| Dokumente | documents:read | Dateien/Dokumente lesen |
| Dokumente | documents:write | Dateien hochladen und löschen |
| Rechnungen | invoices:read | Rechnungen und Gutschriften lesen |
| Rechnungen | invoices:write | Rechnungen erstellen, festschreiben, versenden, stornieren |
| Angebote | offers:read | Angebote und Auftragsbestätigungen lesen |
| Angebote | offers:write | Angebote erstellen und versenden |
| Artikel | articles:read | Artikel/Leistungen lesen |
| Artikel | articles:write | Artikel/Leistungen verwalten |
| Belege | receipts:read | Belege lesen |
| Belege | receipts:write | Belege hochladen, bearbeiten, festschreiben |
| Bank | banking:read | Bankkonten und Umsätze lesen |
| Bank | banking:write | Umsätze importieren und zuordnen |
| Projekte | projects:read | Projekte lesen |
| Projekte | projects:write | Projekte verwalten |
| Zeiterfassung | time:read | Zeiteinträge lesen |
| Zeiterfassung | time:write | Zeiten erfassen und ändern |
| Auswertungen | reports:read | Auswertungen (EÜR, USt-Voranmeldung) und DATEV-Export |
| Buchhaltung | accounting:read | Buchungsjournal, Kontenrahmen, Buchhaltungs-Einstellungen und Festschreibungen lesen |
| Buchhaltung | accounting:write | Manuelle Buchungen, Buchhaltungs-Einstellungen, Festschreibung von Zeiträumen |
| Webhooks | webhooks:read | Webhook-Endpunkte und Zustellungen lesen |
| Webhooks | webhooks:write | Webhook-Endpunkte verwalten |
| Recherche (Adresse, Melderegister, Social Media) | research:read | Adressrecherche, Melderegisteranfragen und Social-Media-Profile lesen |
| Recherche (Adresse, Melderegister, Social Media) | research:write | Melderegisteranfragen stellen (kostenpflichtig) und Social-Media-Profile pflegen |
| Gläubiger-KI | ai:read | Empfehlungen der Gläubiger-KI lesen |
| Gläubiger-KI | ai:write | Empfehlungen der Gläubiger-KI erzeugen (begrenztes KI-Kontingent) |
| Aktivitätsprotokoll | activity:read | Aktivitätsprotokoll (Verlauf über alle Objekte) lesen |
| Aktivitätsprotokoll | activity:write | Eigene Einträge im Aktivitätsprotokoll anlegen |
Nur im Dashboard
Kontoverwaltung ist an keinen Scope gebunden und nur mit einer Dashboard-Anmeldung möglich: API-Schlüssel anlegen und widerrufen, OAuth-Apps registrieren, verbundene Apps trennen, Passkeys und Zwei-Faktor-Anmeldung, Konto löschen. Versucht ein API-Schlüssel oder OAuth-Token das, antwortet die API mit 403 session_required.
Webhooks und Scopes
Ein Webhook-Endpunkt erhält nur Ereignisse, für die der anlegende Schlüssel bzw. die App den passenden Lese-Scope hat – zum Beispiel invoice.paid nur mit invoices:read. Der benötigte Scope steht im Ereigniskatalog auf der Seite Webhooks.