L’API et les clés API

Un assistant comme Claude ou ChatGPT se connecte avec la page d’autorisation de To Bill : voir Connecter un assistant IA. Un outil qui n’a pas cette page, un script, un client MCP en ligne de commande ou une automatisation, utilise une clé API personnelle. Cette page explique les clés et donne les adresses techniques.

Les adresses

Quoi	Adresse
Serveur MCP (assistants IA)	https://app.tobill.ch/mcp
API de To Bill	https://app.tobill.ch/api/…
Découverte OAuth	https://app.tobill.ch/.well-known/oauth-authorization-server
Référence de l’API (bêta)	https://docs.tobill.ch/api

Le serveur MCP donne à l’assistant des outils prêts à l’emploi pour la comptabilité et la facturation, plus deux outils qui ouvrent tout le reste de To Bill : l’un cherche la bonne route de l’API, l’autre l’appelle, avec les mêmes contrôles que l’app.

La référence de l’API décrit chaque route qu’une clé ouvre, avec ses paramètres, ses réponses et des exemples ; sa version interactive permet d’essayer une requête avec votre clé.

Créer une clé

1. Ouvrez Paramètres › Connexions IA et API.
2. Sous Clés API personnelles, cliquez sur Créer une clé.
3. Donnez-lui un Nom qui dit à quoi elle sert, choisissez l’Accès (Lecture seule ou Lecture et modification) et la Durée (30, 90 ou 365 jours), puis cliquez sur Créer la clé.
4. Copiez la clé : elle ne s’affiche qu’une fois. Puis cliquez sur J’ai copié la clé.

La clé commence par tb_pk_. Elle ouvre l’entreprise où vous étiez en la créant, avec vos droits dans cette entreprise. La liste montre ensuite son début, son accès, son entreprise, sa date d’expiration et sa dernière utilisation, jamais la clé entière.

Une clé est un mot de passe

Quiconque a la clé agit dans To Bill en votre nom. Ne la mettez ni dans un e-mail, ni dans un document partagé, ni dans un dépôt de code. Une clé perdue se révoque tout de suite (voir plus bas) et se remplace par une nouvelle.

Envoyer la clé

Chaque requête porte la clé dans l’en-tête HTTP Authorization, comme jeton Bearer :

curl https://app.tobill.ch/api/clients -H "Authorization: Bearer tb_pk_…"

Claude Code avec une clé

claude mcp add --transport http tobill https://app.tobill.ch/mcp --header "Authorization: Bearer tb_pk_…"

Ce qu’une clé ouvre et ce qu’elle n’ouvre pas

• Avec Lecture seule, la clé lit seulement : toute modification est refusée.
• Avec Lecture et modification, elle fait ce que vous pouvez faire dans l’entreprise, avec les mêmes contrôles que l’app, et jamais plus que les droits de votre rôle.
• Elle n’ouvre ni la connexion à votre compte, ni l’abonnement, ni les paiements, ni la gestion des connexions et des clés, ni une autre entreprise, ni le cockpit d’une fiduciaire.
• Chaque modification faite avec la clé est inscrite dans l’activité de l’entreprise sous le nom que vous lui avez donné.
• To Bill limite le nombre de requêtes par minute et par clé ; au-delà, il refuse les requêtes pendant un moment et l’outil doit attendre avant de réessayer.

Révoquer une clé

Dans Paramètres › Connexions IA et API, cliquez sur Révoquer à côté de la clé, puis confirmez. Elle ne fonctionne plus, tout de suite. Une clé arrivée à expiration reste dans la liste, marquée Expirée, jusqu’à ce que vous la révoquiez.