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 hat eine oder beide Berechtigungen. Welche Berechtigung ein Endpunkt braucht, steht in der Referenz bei jedem Endpunkt.
| Berechtigung | In der App | Erlaubt |
|---|---|---|
read | Daten lesen | alle lesenden Endpunkte: Belege, Belegdateien, Kontakte, Bankkonten, Umsätze, Sachkonten, Buchungen, Tarif |
upload | Belege hochladen | Beleg hochladen |
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.
- 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 oder eine Freischaltung durch bimetrics antwortet die API mit
403und dem CodeAPIUnavailable. - Ein Passwortwechsel widerruft keine Schlüssel.
Sicher aufbewahren
Nie im Frontend-Code
Wer den Schlüssel kennt, hat bis zum Ablauf vollen Lesezugriff auf die Daten der Firma und kann, mit der Berechtigung upload, Belege hochladen. 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.