Créer un token d’accès à l’API bexio

Qui cherche une « clé API bexio » ne trouve aucun bouton pour cela dans bexio. Aujourd’hui, l’accès à l’API bexio passe par deux voies : un token d’accès personnel pour vos propres scripts, ou une app dans le Developer Portal qui se connecte via OAuth 2. Ce guide montre les deux voies, le premier appel avec le token et les erreurs qui bloquent le plus souvent au départ.

Existe-t-il une clé API bexio ?

Non, plus maintenant. La documentation décrivait autrefois des « API Tokens » fixes pour les connexions de serveur à serveur. En octobre 2024, bexio a remplacé cette section par les tokens d’accès personnels, en anglais « Personal Access Tokens », PAT en abrégé. Les anciens guides qui promettent une clé permanente tirée des paramètres sont donc dépassés.

Aujourd’hui, chaque requête vers https://api.bexio.com a besoin d’un token d’accès dans l’en-tête Authorization: Bearer …. La provenance du token dépend de qui utilise la connexion :

• Vous seul, par exemple pour un script, un export ou un test : token d’accès personnel (voie 1).
• Une application pour d’autres, par exemple un plugin sur un site ou un service pour plusieurs entreprises : app dans le Developer Portal avec OAuth 2 (voie 2).

La référence de tous les points d’accès se trouve sur docs.bexio.com. Pour essayer sans vraie comptabilité, bexio propose un compte d’essai à ouvrir sur bexio.com.

Voie 1 : créer un Personal Access Token

1. Ouvrir developer.bexio.com/pat et se connecter avec le compte bexio.
2. Créer un nouveau token et le ranger tout de suite en lieu sûr, par exemple dans un gestionnaire de mots de passe ou un fichier que vous seul pouvez lire.
3. Envoyer le token depuis le script comme bearer token.

Selon la documentation, un PAT fonctionne ainsi :

• Accès complet : un PAT a tous les droits par défaut et donc accès à toutes les données de l’entreprise. Qui le connaît peut lire les factures et modifier les contacts.
• Valable 60 jours : ensuite il expire, et le script en a besoin d’un nouveau.
• Révocation par suppression : un token supprimé ne peut plus être utilisé. Il peut falloir jusqu’à une heure pour que la révocation s’applique partout.
• Pour un usage personnel uniquement : pour limiter les droits, par exemple à la seule lecture des contacts, passez par une app.

Tester le token

Le test le plus simple est une liste des contacts :

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

Si une liste JSON revient, l’accès fonctionne. L’API signale les erreurs par un code de statut HTTP et un court texte JSON avec error_code et message. Un appel à /3.0/users/me montre en outre sous quel utilisateur le token travaille. C’est important, car l’API n’a jamais plus de droits que cet utilisateur dans bexio.

Le token n’a rien à faire dans un dépôt Git public, dans du JavaScript côté navigateur ou dans un e-mail. S’il a malgré tout été exposé : le supprimer dans le Developer Portal et en créer un nouveau.

Voie 2 : app dans le Developer Portal avec OAuth 2

Pour tout ce que d’autres personnes ou entreprises connectent, un PAT n’est pas la bonne voie. Il faut alors une app :

1. Se connecter au Developer Portal et accepter les conditions d’utilisation. bexio renvoie en particulier au chiffre 4.4 sur l’usage commercial.
2. Créer une app et saisir les URL de redirection autorisées, c’est-à-dire les adresses vers lesquelles bexio renvoie après la connexion.
3. Relever l’ID client et le secret client sous « App Details ». Le secret reste sur le serveur.
4. Faire connecter l’utilisateur via l’« Authorization Code Flow » sur auth.bexio.com. Il y voit les droits demandés par l’app et les confirme.

Ces droits s’appellent des scopes, par exemple contact_show pour lire les contacts ou kb_invoice_edit pour modifier les factures. Un droit d’écriture inclut le droit de lecture. Avec le scope offline_access, l’app reçoit en plus un refresh token qui lui permet d’obtenir de nouveaux tokens d’accès sans que l’utilisateur se reconnecte. Le guide Connecter l’API bexio à WordPress montre à quoi cela ressemble dans WordPress.

Quelle voie choisir ?

Erreurs fréquentes

• Token expiré : un script qui tournait depuis deux mois s’arrête soudain. Le plus souvent, le PAT a expiré après 60 jours.
• Droits de l’utilisateur manquants : l’API travaille avec les droits de l’utilisateur qui a créé le token ou connecté l’app. S’il n’a pas accès aux contacts dans bexio, le bon scope n’y change rien.
• Nouveaux scopes au renouvellement : en renouvelant un token, les droits restent les mêmes. Si l’app a besoin de plus, l’utilisateur doit se reconnecter.
• URL de redirection différente : si l’adresse ne figure pas exactement ainsi dans l’app, la connexion s’interrompt avec un message d’erreur.
• Trop de requêtes : l’API limite les requêtes par minute et par entreprise. Une fois la limite atteinte, elle renvoie le statut 429 ; les en-têtes RateLimit-Remaining et RateLimit-Reset indiquent combien de temps attendre.
• Pas de fichier OpenAPI : selon sa propre documentation, bexio ne fournit pas de description OpenAPI. Un client ne se génère donc pas automatiquement, il s’écrit d’après la référence.
• Panne plutôt qu’erreur : si l’API ne répond pas du tout, un coup d’œil à la page de statut bexio-status.com vaut mieux que de chercher dans son propre code.

Solutions prêtes à l’emploi

Si vous ne voulez pas gérer de token vous-même, une connexion prête à l’emploi existe pour les cas les plus fréquents :

• Connecteur de formulaires bexio : plugin WordPress, les demandes du formulaire du site deviennent des contacts avec note dans bexio. La connexion se fait d’un clic sur « Se connecter à bexio », sans app propre et sans token à renouveler tous les 60 jours.
• Connecter l’API bexio à WordPress : la voie avec votre propre app, pas à pas, si vous construisez vous-même.

Tous les guides