bexio API Token erstellen

Wer nach einem «bexio API Key» sucht, findet in bexio selbst keinen Knopf dafür. Den Zugang zur bexio API gibt es heute auf zwei Wegen: als persönliches Zugriffstoken für eigene Skripte oder als App im Developer Portal, die sich per OAuth 2 anmeldet. Diese Anleitung zeigt beide Wege, den ersten Aufruf mit dem Token und die Fehler, an denen der Start meist scheitert.

Gibt es einen bexio API Key?

Nein, nicht mehr. Früher beschrieb die Doku feste «API Tokens» für Verbindungen von Server zu Server. Im Oktober 2024 hat bexio diesen Abschnitt durch die persönlichen Zugriffstoken ersetzt, englisch «Personal Access Tokens», kurz PAT. Alte Anleitungen, die einen unbefristeten Schlüssel aus den Einstellungen versprechen, sind darum überholt.

Heute gilt: Jede Anfrage an https://api.bexio.com braucht ein Access-Token im Header Authorization: Bearer …. Woher das Token kommt, hängt davon ab, wer die Verbindung nutzt:

Nur Sie selbst, etwa für ein Skript, einen Export oder einen Test: persönliches Zugriffstoken (Weg 1).
Eine Anwendung für andere, etwa ein Plugin auf einer Website oder ein Dienst für mehrere Firmen: App im Developer Portal mit OAuth 2 (Weg 2).

Die Referenz aller Endpunkte steht unter docs.bexio.com. Zum Ausprobieren ohne echte Buchhaltung bietet bexio ein Testkonto an, das man auf bexio.com eröffnet.

Weg 1: Personal Access Token erstellen

Die Seite developer.bexio.com/pat öffnen und mit dem bexio-Konto anmelden.
Ein neues Token erstellen und sofort an einem sicheren Ort ablegen, etwa in einem Passwortmanager oder einer Datei, die nur Sie lesen dürfen.
Das Token im Skript als Bearer-Token mitschicken.

Was laut Doku für ein PAT gilt:

Voller Zugriff: Ein PAT hat alle Standardrechte und damit Zugriff auf alle Daten der Firma. Wer es kennt, kann Rechnungen lesen und Kontakte ändern.
60 Tage gültig: Danach ist es abgelaufen, und das Skript braucht ein neues.
Widerruf durch Löschen: Ein gelöschtes Token lässt sich nicht mehr verwenden. Bis der Widerruf überall greift, kann es bis zu einer Stunde dauern.
Nur für den eigenen Gebrauch: Wer die Rechte einschränken will, etwa nur Kontakte lesen, nimmt den Weg über eine App.

Den Token testen

Der einfachste Test ist eine Liste der Kontakte:

curl https://api.bexio.com/2.0/contact \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Token>'

Kommt eine JSON-Liste zurück, stimmt der Zugang. Fehler meldet die API mit einem HTTP-Statuscode und einem kurzen JSON-Text mit error_code und message. Ein Aufruf von /3.0/users/me zeigt ausserdem, unter welchem Benutzer das Token arbeitet. Das ist wichtig, denn die API hat nie mehr Rechte als dieser Benutzer in bexio.

Das Token gehört nie in ein öffentliches Git-Repository, in JavaScript im Browser oder in eine Mail. Ist es doch einmal sichtbar geworden: im Developer Portal löschen und ein neues erstellen.

Weg 2: App im Developer Portal mit OAuth 2

Für alles, was andere Personen oder Firmen verbinden, ist ein PAT der falsche Weg. Dann braucht es eine eigene App:

Im Developer Portal anmelden und die Nutzungsbedingungen annehmen. bexio verweist dabei besonders auf Ziffer 4.4 zur kommerziellen Nutzung.
Eine App anlegen und die erlaubten Redirect-URLs eintragen, also die Adressen, auf die bexio nach der Anmeldung zurückleitet.
Unter «App Details» Client-ID und Client-Secret ablesen. Das Secret bleibt auf dem Server.
Den Benutzer über den «Authorization Code Flow» auf auth.bexio.com anmelden lassen. Er sieht dort, welche Rechte die App verlangt, und bestätigt sie.

Die Rechte heissen Scopes, etwa contact_show für Kontakte lesen oder kb_invoice_edit für Rechnungen bearbeiten. Ein Schreibrecht schliesst das Leserecht ein. Mit dem Scope offline_access erhält die App zusätzlich ein Refresh-Token, mit dem sie sich neue Access-Tokens holt, ohne dass sich der Benutzer neu anmeldet. Wie das in WordPress aussieht, zeigt der Ratgeber bexio API mit WordPress verbinden.

Welcher Weg passt?

Frage	Personal Access Token	App mit OAuth 2
Wer nutzt die Verbindung?	Sie selbst	andere Benutzer oder Firmen
Rechte	alle Daten der Firma	nur die verlangten Scopes
Gültigkeit	60 Tage	so lange, wie das Refresh-Token regelmässig erneuert wird
Aufwand	wenige Minuten	Anmeldung, Token-Speicher, Erneuerung
Typischer Einsatz	Export, Test, eigenes Skript	Plugin, Integration, Dienst

Häufige Fehler

Abgelaufenes Token: Ein Skript, das zwei Monate lief, bricht plötzlich ab. Meist ist das PAT nach 60 Tagen abgelaufen.
Fehlende Rechte des Benutzers: Die API arbeitet mit den Rechten des Benutzers, der das Token erstellt oder die App verbunden hat. Fehlt ihm in bexio der Zugriff auf Kontakte, hilft auch der passende Scope nicht.
Neue Scopes bei der Erneuerung: Beim Erneuern eines Tokens bleiben die Rechte gleich. Braucht die App mehr, muss sich der Benutzer neu anmelden.
Redirect-URL weicht ab: Steht die Adresse nicht genau so in der App, bricht die Anmeldung mit einer Fehlermeldung ab.
Zu viele Anfragen: Die API begrenzt die Anfragen pro Minute und Firma. Wird die Grenze erreicht, kommt Status 429; die Header RateLimit-Remaining und RateLimit-Reset sagen, wie lange zu warten ist.
Keine OpenAPI-Datei: bexio bietet laut eigener Doku keine OpenAPI-Beschreibung an. Einen Client erzeugt man also nicht automatisch, sondern schreibt ihn anhand der Referenz.
Störung statt Fehler: Antwortet die API gar nicht, lohnt ein Blick auf die Statusseite bexio-status.com, bevor man den eigenen Code sucht.

Fertige Lösungen

Wer kein eigenes Token verwalten will, kann für die häufigsten Fälle eine fertige Anbindung nehmen:

bexio-Formular-Connector: WordPress-Plugin, Anfragen aus dem Website-Formular werden zu Kontakten mit Notiz in bexio. Verbunden wird mit einem Klick auf «Mit bexio verbinden», ohne eigene App und ohne Token, das jemand alle 60 Tage erneuern muss.
bexio API mit WordPress verbinden: der Weg mit eigener App Schritt für Schritt, falls Sie selbst bauen.

Alle Ratgeber