Authentifizierung und Scopes
Wie der API-Schlüssel gesendet wird, welche Berechtigungen er hat und wie lange er gilt.
Schlüssel senden
Sende den Schlüssel in genau einem Header, ausschließlich über HTTPS:
Authorization: Bearer bm_…Alternativ akzeptiert die API denselben Schlüssel im Header X-API-KEY:
X-API-KEY: bm_…Abgelehnt werden mit 401:
- beide Header zugleich oder ein Header mehrfach,
- der Schlüssel als URL-Parameter (
?token=…) oder per Basic-Auth, - ein Schlüssel mit angehängter Firmen-ID (
bm_…:<id>).
Die Firma ergibt sich aus dem Schlüssel. Ein Schlüssel besteht aus bm_ und 43 Zeichen aus dem URL-sicheren Base64-Alphabet, insgesamt 46 Zeichen. Antworten auf Aufrufe mit Schlüssel tragen Cache-Control: no-store.
Berechtigungen (Scopes)
Jeder Schlüssel erhält ausdrücklich ausgewählte Berechtigungen. Welche Berechtigung ein Endpunkt braucht, steht in der Referenz bei jedem Endpunkt. Zusätzliche Schreibrechte müssen ausdrücklich vergeben werden.
| Berechtigung | In der App | Erlaubt |
|---|---|---|
read | Daten lesen | Belege und Belegdateien, Duplikate und Löschvorschau, Kontakte, Bankkonten und Bankzugänge, Umsätze, Sachkonten, Kategorien, Buchungen, Zuordnungen mit Vorschlägen und Vorschauen, Buchungsvorlagen und Dauerbuchungen, eingelesene Kontoauszüge, „Zu erledigen“, Firma und Logo, Tarif; dazu alles aus contacts:read und sales:read |
upload | Belege hochladen | Beleg hochladen |
contacts:read | Kontakte lesen | Kontakte abrufen, IBAN, USt-IdNr. und PLZ vorab prüfen, Ort aus PLZ |
sales:read | Ausgangsrechnungen und Entwürfe lesen | Entwürfe, Ausgangsrechnungen und Auftragsbestätigungen mit PDF und ausgestelltem XML, Korrekturumfang und Korrekturguthaben, Forderungen, Mahnungen und Mahnstufen, Serienvorlagen, die Mail-Vorschau und Rechnungslayouts mit Vorschau |
contacts:write | Kontakte anlegen und ändern | erlaubte Kontaktfelder schreiben |
invoices:draft | Rechnungsentwürfe verwalten | Entwürfe anlegen, ändern, prüfen und löschen, Folgedokumente ableiten, Rechnungskorrekturen als Entwurf, Mahnungen und Mahnstufen, wiederkehrende Rechnungen als Entwurf |
invoices:finalize | Ausgangsrechnungen erstellen und stornieren | gespeicherte Entwürfe abschließen, Vollstornos erstellen, Rechnungskorrekturen aufheben; zusammen mit invoices:draft wiederkehrende Rechnungen, die selbst ausstellen |
matching:write | Belege und Zahlungen zuordnen | Zuordnungen anlegen, erweitern und lösen, Skonto und Mahnkosten ausgleichen, Vorschläge ausblenden, Zahlungen erfassen und zurücknehmen, Erstattungen und Verrechnungen. Löst du eine Zuordnung, werden aus Buchungsvorlagen erzeugte Belege mit gelöscht |
documents:write | Nicht an DATEV exportierte Belege ändern | Belege berichtigen, Kategorie oder Belegart für bis zu 50 Belege setzen |
mail:send | E-Mails senden | ausgestellte Rechnungen, Stornos, Korrekturen, Angebote, Auftragsbestätigungen und Mahnungen per E-Mail senden |
layout:write | Layouts und Logo ändern | Rechnungslayouts anlegen, ändern, zuweisen, archivieren und frühere Versionen wiederherstellen; Logo hochladen, verbessern und löschen |
company:write | Firmendaten ändern | Firmendaten und Kostenstellen wie in den Einstellungen ändern, ohne Kontenrahmen, Versteuerung und Bankverbindung |
documents:delete | Belege löschen | Belege und Duplikat-Einträge löschen; Festgeschriebene werden storniert, an DATEV Exportierte bleiben in der App |
collections:write | Vorlagen und Dauerbuchungen ändern | eigene Buchungsvorlagen und Dauerbuchungen anlegen, ändern und löschen; Standardvorlagen nur in der App |
statements:import | Kontoauszüge einlesen | Dateien der Bank hochladen, ansehen und nach einer Vorschau als Umsätze übernehmen, wie in der App |
inbox:read | Postfach lesen | Mails im Belegpostfach mit Text und Anhängen lesen; nicht in read enthalten |
inbox:write | Postfach bearbeiten | Anhänge als Belege übernehmen, Mails ablegen und zurückholen; Mails löschen geht nur in der App |
Auch bestehende Schlüssel mit read können Zuordnungen, Rechnungen und Entwürfe einschließlich ausgestelltem XML lesen. Schreibrechte werden einzeln vergeben; sie schließen Leserechte nicht automatisch ein. Siehe Schreiboperationen für Wiederholungen und Versionsprüfung.
Fehlt die Berechtigung oder ist ein Endpunkt nicht für API-Schlüssel freigegeben, antwortet die API mit 403 und dem Code APIKeyPermissionDenied. Vergib nur die Berechtigungen, die die Anwendung braucht.
Laufzeit und Anzahl
- Ein Schlüssel gilt 30, 90 oder 365 Tage ab dem Anlegen. Danach antwortet die API mit
401. Eine automatische Verlängerung gibt es nicht. - Eine Firma hat höchstens fünf aktive Schlüssel gleichzeitig und legt höchstens zehn neue Schlüssel je Tag (UTC) an, widerrufene mitgezählt.
- Zum Austauschen legst du einen neuen Schlüssel an, stellst die Anwendung um und widerrufst dann den alten.
Bindung an Inhaber und Tarif
Ein Schlüssel gehört zum Inhaber, der ihn angelegt hat, und zur gewählten Firma. Jeder Aufruf prüft Schlüssel, Ablauf, Widerruf, Mitgliedschaft und Tarif neu.
- Endet die Mitgliedschaft des Erstellers oder verliert er die Inhaberrolle, werden seine Schlüssel dauerhaft widerrufen.
- Ohne gültigen bezahlten Tarif, Freischaltung durch bimetrics oder laufende Testphase antwortet die API mit
403und dem CodeAPIUnavailable. Nach dem Ende der Testphase bleiben Schlüssel in der App sichtbar und lassen sich widerrufen; mit einem Tarif funktionieren sie wieder. - Ein Passwortwechsel widerruft keine Schlüssel.
Sicher aufbewahren
Nie im Frontend-Code
Wer den Schlüssel kennt, kann seine erteilten Lese- und Schreibrechte bis zum Ablauf oder Widerruf nutzen. Baue ihn nie in Browser-, Mobil- oder Desktop-Apps ein, die an Dritte gehen.
- Lege den Schlüssel nur serverseitig ab, etwa in einer Umgebungsvariable oder einem Secret-Store.
- Schreibe ihn nicht in URLs, Logs, Tickets oder Quellcode.
- Nutze je Anwendung einen eigenen Schlüssel. So kannst du einen einzelnen Zugang widerrufen, ohne andere zu stören.
Widerrufen
Widerrufe einen Schlüssel in der App unter Einstellungen › API mit Widerrufen. Ab dann antwortet die API auf neue Aufrufe mit 401; bereits laufende Aufrufe werden nicht abgebrochen. Widerrufe einen Schlüssel sofort, wenn er in falsche Hände geraten sein könnte oder du einen Zugang nicht kennst.