bexio-API: Zugang und Token einrichten

Zugang zur bexio-API erhalten Sie über das Entwicklerportal unter developer.bexio.com, angemeldet mit Ihren bexio-Zugangsdaten. Sie haben zwei Möglichkeiten: einen Personal Access Token für den persönlichen Gebrauch oder eine eigene App mit Client ID, Client Secret und frei gewählten Scopes. Welche Daten eine Anbindung am Ende sehen und ändern darf, bestimmen zwei Ebenen gemeinsam: der Scope der App und das Benutzerrecht der Person, die die Verbindung einrichtet.

Voraussetzungen

• bexio-Konto: Zum Entwickeln nennt bexio einen API-Sandbox-Account, der speziell für Entwicklungszwecke gedacht ist. Auf der API-Seite von bexio finden Sie ihn unter «Sandbox Account erstellen».
• Anmeldung im Entwicklerportal: Sie loggen sich mit bexio-Zugangsdaten ein und akzeptieren die Bedingungen. Die Dokumentation verweist dabei besonders auf die Regeln zur kommerziellen Nutzung. Nach den Marketplace-AGB müssen Sie ein eigenständiges Geschäftsmodell auf Basis der API melden, sobald mindestens fünf bexio-Konten verbunden sind.
• Rechte in bexio: Die Verwaltung von API-Schlüsseln nennt die Hilfe in den Einstellungen ausdrücklich nur für den Superadmin. Die Anbindung arbeitet mit den Rechten der Person, die sie eingerichtet hat.

Weg 1: Personal Access Token

Ein Personal Access Token, kurz PAT, eignet sich für Skripte und Tests, die nur Sie selbst nutzen.

1. Öffnen Sie developer.bexio.com/pat und melden Sie sich mit Ihren bexio-Zugangsdaten an.
2. Erstellen Sie dort einen Token. Kopieren Sie ihn und bewahren Sie ihn geschützt auf.
3. Senden Sie ihn bei jeder Anfrage im Header Authorization: Bearer <Token> mit.

Das müssen Sie wissen:

• Ein PAT hat alle Standard-Scopes und damit vollen Zugriff auf die Daten Ihrer Firma.
• Er gilt 60 Tage nach der Erstellung.
• Sie widerrufen ihn, indem Sie ihn im Portal löschen. Danach funktioniert er nicht mehr. Im ungünstigsten Fall dauert es bis zu eine Stunde, bis der Widerruf überall wirkt.
• Geben Sie einen PAT niemals weiter. Müssen Zugangsdaten mit einer anderen Partei geteilt werden, brauchen Sie den OAuth-Weg.
• Möchten Sie die Scopes einschränken, verwenden Sie ebenfalls OAuth.

Weg 2: eigene OAuth-App

Eine App ist die richtige Wahl für Anbindungen im Dauerbetrieb und für alles, was Dritte nutzen.

1. Melden Sie sich im Entwicklerportal an und akzeptieren Sie die Bedingungen.
2. Legen Sie eine neue App an und tragen Sie mindestens eine gültige «Allowed redirect URL» ein. Bis zu zehn sind möglich, etwa für Test und Produktion. Unbekannte Adressen lehnt bexio bei der Anmeldung ab.
3. Öffnen Sie «App Details». Dort sehen Sie Client ID und Client Secret.
4. Starten Sie den Authorization Code Flow, um ein Access Token zu erhalten. Der Ablauf Schritt für Schritt steht im Beitrag bexio-API: erste Schritte für Entwickler.

Legen Sie für die Produktion eine zweite App mit eigener Client ID und eigenem Client Secret an. Das empfiehlt die Dokumentation ausdrücklich. Das Client Secret darf nie in einer Browser-App, in öffentlichem Code oder in einer Nachricht stehen. Wie Sie Schlüssel schützen und erneuern, erklärt der Beitrag Schnittstellen sicher betreiben.

Scopes: nur anfordern, was nötig ist

Ein Scope begrenzt, worauf eine App zugreifen darf. Beim Verbinden zeigt bexio dem Benutzer eine Zustimmungsseite mit den angeforderten Berechtigungen. Mehrere Scopes trennen Sie mit einem Leerzeichen. Eine Auswahl aus der Dokumentation:

Fordern Sie ein Schreibrecht an, ist der Lesezugriff auf dieselbe Ressource enthalten. Daneben gibt es Scopes für die Anmeldung: openid, profile, email, company_profile und offline_access. Mit offline_access bleibt ein Refresh Token nutzbar, auch wenn die Sitzung des Benutzers beendet ist. Welcher Scope für welchen Endpunkt nötig ist, steht bei jedem Endpunkt in der Dokumentation und ändert sich gelegentlich. Prüfen Sie ihn vor dem Bau.

Scope und Benutzerrecht müssen zusammenpassen

bexio prüft jede Anfrage auf zwei Ebenen. Der Scope hängt an der App, das Benutzerrecht an der Person, die die Verbindung eingerichtet hat.

Praktisch heisst das: Hat die Person kein Recht auf Kontakte, sieht auch eine App mit contact_show keine. Richten Sie eine Verbindung deshalb mit einem Benutzer ein, der genau die nötigen Rechte hat und nicht mehr. Das ist eine Empfehlung und keine Vorgabe der Dokumentation. Wie Benutzerrechte in bexio gesetzt werden, zeigt der Beitrag Benutzer und Rechte in bexio verwalten. Meldet die Schnittstelle trotz Token 401 oder 403, hilft der Beitrag bexio-Schnittstelle meldet 401 oder 403.

Zugriff kontrollieren und widerrufen

• Apps in bexio: Unter «Alle Einstellungen» → «Apps & API» → «Apps» sehen Sie die verbundenen Anwendungen. Mit «Entfernen» beenden Sie die Berechtigung. Die Hilfe zeigt das am Beispiel von Zapier.
• Personal Access Tokens: Löschen Sie sie im Entwicklerportal.
• Scopes ändern: Beim Erneuern eines Tokens bleiben die Scopes gleich. Neue Scopes erhalten Sie nur, wenn der Benutzer die Verbindung erneut freigibt.

Häufige Fragen

Kostet der API-Zugang etwas?

Laut bexio-Hilfe steht für die Nutzung der API mit OAuth eine kostenfreie Zugriffsmöglichkeit zur Verfügung. Kosten entstehen durch Entwicklung, Betrieb oder Apps von Dritten. Für Dienstleister mit eigenem Geschäftsmodell gelten die Regeln der Marketplace-AGB.

Was geschieht, wenn mein Token abläuft?

Ein PAT gilt 60 Tage. Danach stellen Sie im Portal einen neuen aus und tragen ihn in Ihrer Anwendung ein. Für Dauerbetrieb eignet sich der OAuth-Weg mit offline_access besser.

Wer unterstützt mich bei der Umsetzung?

bexio bietet keine Auftragsentwicklung und keine Implementierungsunterstützung. Fehler in der Schnittstelle melden Sie über das Formular der Dokumentation, ohne Zugangsdaten mitzusenden.

Fazit

Für den persönlichen Gebrauch genügt ein Personal Access Token. Alles, was dauerhaft läuft oder von Dritten genutzt wird, gehört in eine OAuth-App mit knapp gewählten Scopes. Beachten Sie, dass Scope und Benutzerrecht gemeinsam entscheiden, und halten Sie Tokens und Client Secret geheim. Mit zwei getrennten Apps für Test und Produktion bleiben Ihre echten Daten geschützt.