bexio-Schnittstelle meldet 401 oder 403

Ein 401 bedeutet laut der bexio-API-Dokumentation, dass das Bearer-Token oder der übergebene API-Schlüssel ungültig ist. Erstellen oder erneuern Sie dann das Token. Ein 403 heisst, dass dem Zugang die nötigen Rechte fehlen. Prüfen Sie dann die Scopes der App und die Benutzerrechte der Person, die die Verbindung eingerichtet hat.

Symptome erkennen

Die Schnittstelle antwortet mit einem HTTP-Status und einem JSON-Text mit den Feldern error_code und message.

Ursachen und Lösungen bei 401

1. Anfrage prüfen. Jede Anfrage braucht die Header «Accept: application/json» und «Authorization: Bearer <token>». Die Adresse beginnt mit https://api.bexio.com. Kopieren Sie das Token vollständig und ohne Leerzeichen.
2. Art des Zugangs bestimmen. Ein PAT ist ein persönliches Token und gilt 60 Tage. Ein OAuth-Zugang liefert Access- und Refresh-Token über den Authorization Code Flow. Die Art entscheidet, wie Sie erneuern.
3. PAT erneuern. Erstellen Sie ein neues PAT. Verwaltet werden PATs laut Dokumentation im Entwicklerportal von bexio. Ein gelöschtes PAT lässt sich nicht mehr verwenden. Im ungünstigsten Fall dauert es bis zu einer Stunde, bis der Widerruf vollständig wirkt. Teilen Sie ein PAT mit niemandem. Für eine Weitergabe nutzen Sie den Authorization Code Flow.
4. Refresh-Token verwenden. Für ein Refresh-Token braucht die App den Scope offline_access. Senden Sie eine Anfrage an den Token-Endpunkt mit dem Grant-Typ refresh_token. Ersetzen Sie das gespeicherte Refresh-Token jedes Mal durch das neue. Offline-Sitzungen werden geschlossen, wenn sie nicht innerhalb von einem Jahr erneuert werden.
5. Alten Anmeldeserver ablösen. Die Dokumentation kündigte an, den Server idp.bexio.com am 31. März 2025 ausser Betrieb zu nehmen. Verwenden Sie auth.bexio.com/realms/bexio. Parameter für den Token-Endpunkt gehören in den Request-Body, nicht in die Adresse.
6. Alte API erkennen. Funktioniert Ihre Anbindung an die bexio legacy API nicht mehr, liegt das an deren Abschaltung. In der Dokumentation ist der 30. November 2023 als Termin genannt. Die Dokumentation der alten API wurde im Februar 2024 entfernt. Für fertige Anbindungen von Drittanbietern wenden Sie sich laut bexio-Hilfe an den Anbieter. bexio bietet für Partner-Anbindungen keinen Support. Entwickler stellen auf die aktuelle API um, wie in bexio-API: Änderungen und alte API beschrieben.
7. Werkzeuge von Dritten prüfen. Bricht ein Zap ab, wurde die Verbindung entfernt oder ist abgelaufen. Das Erneuern beschreibt Zapier-Verbindung zu bexio erneuern.

Ursachen und Lösungen bei 403

1. Scopes der App prüfen. Ein Scope begrenzt, worauf eine App zugreifen darf. Lesezugriff gibt es automatisch, wenn ein Schreib-Scope angefordert wird. Beispiel: Mit contact_edit ist contact_show nicht nötig. Beim Aktualisieren eines Tokens ändern sich die Scopes nicht. Neue Scopes erhalten Sie nur, wenn der Nutzer die App erneut autorisiert. Das Änderungsprotokoll der Dokumentation nennt am 19. Juni 2026 aktualisierte Scopes für Einkaufsrechnungen, Zahlungen und Aufwendungen. Prüfen Sie bei einem 403 an diesen Endpunkten die Scopes Ihrer App.
2. Benutzerrechte der verbindenden Person prüfen. Der Zugriff erfolgt mit den Rechten der Person, die die Verbindung eingerichtet hat. Es müssen beide Ebenen passen. Hat die Person das Recht im bexio-Menü nicht, wird der Zugriff verweigert, selbst wenn die App den Scope besitzt. Fehlt umgekehrt der Scope, nützt das Benutzerrecht nichts. Wie Sie Rechte kontrollieren, steht in Menü oder Daten fehlen: Benutzerrechte prüfen.
3. Verbindende Person wechseln. Der Zugriff folgt den Rechten der Person, die die Verbindung eingerichtet hat. Ändern sich deren Rechte, kann sich auch die Anbindung ändern. Richten Sie die Verbindung bei Bedarf mit einer Person ein, die die nötigen Rechte hat.
4. Zugang kontrollieren. In der Hilfe von bexio finden Sie verbundene Apps unter «Alle Einstellungen» → «Apps & API». Von dort lässt sich etwa eine Verbindung entfernen und neu herstellen.

Wann der bexio-Support weiterhilft

Die Schnittstelle wird laut Dokumentation so bereitgestellt, wie sie beschrieben ist. Es gibt keine geführte Einrichtung und keinen Code-Support. Kommen Sie mit der Dokumentation nicht weiter, reproduzieren Sie das Problem mit einem Testwerkzeug wie Postman und melden Sie es über das Formular «Report a problem» der Dokumentation. Beschreiben Sie die Schritte so, dass bexio sie nachstellen kann, und geben Sie keine Zugangsdaten an. Kurzfristige Störungen der Schnittstelle können Sie über die Statusseite von bexio abonnieren. Anbindungen von Partnern unterstützt der jeweilige Anbieter.

Häufige Fragen

Wie lange gilt ein Personal Access Token?

60 Tage nach der Erstellung. Danach erstellen Sie ein neues. Bei Zugängen für Dritte verwenden Sie den Authorization Code Flow statt eines PAT.

Muss ich nach einer Scope-Änderung neu autorisieren?

Ja. Beim Erneuern eines Tokens bleiben die Scopes unverändert. Neue Scopes gibt es nur über eine neue Autorisierung.

Warum bekomme ich 403, obwohl der Scope stimmt?

Dann fehlt vermutlich das Benutzerrecht der Person, die die Verbindung eingerichtet hat. Beide Ebenen müssen den Zugriff erlauben.

Fazit

Bei 401 geht es um das Token, bei 403 um Rechte. Prüfen Sie zuerst Anfrage und Ablauf des Tokens, danach Scopes und Benutzerrechte. Zugänge, die auf der alten API oder auf dem abgeschalteten Anmeldeserver beruhen, müssen Sie umstellen. Behandeln Sie Tokens wie Passwörter und teilen Sie sie nicht.