Documentation

English

Français
Deutsch
Italiano
Español
Português
Shqip

English

Français
Deutsch
Italiano
Español
Português
Shqip

Appearance

The API and API keys ​

An assistant such as Claude or ChatGPT connects through the To Bill authorisation page: see Connect an AI assistant. A tool that does not have this page, such as a script, a command-line MCP client or an automation, uses a personal API key. This page explains the keys and gives the technical addresses.

The addresses ​

WhatAddress
MCP server (AI assistants)https://app.tobill.ch/mcp
To Bill APIhttps://app.tobill.ch/api/…
OAuth discoveryhttps://app.tobill.ch/.well-known/oauth-authorization-server
API reference (beta)https://docs.tobill.ch/api

The MCP server gives the assistant ready-to-use tools for accounting and invoicing, plus two tools that open up the rest of To Bill: one finds the right API route, the other calls it, with the same checks as the app.

The API reference describes every route a key opens, with its parameters, responses and examples; its interactive version lets you try a request with your key.

Create a key ​

  1. Open Settings › AI and API connections.
  2. Under Personal API keys, click Create a key.
  3. Give it a Name that says what it is for, choose the Access (Read only or Read and modify) and how long it is Valid for (30, 90 or 365 days), then click Create the key.
  4. Copy the key: it is only shown once. Then click I have copied the key.

The key starts with tb_pk_. It opens the company you were in when you created it, with your rights in that company. The list then shows its beginning, its access, its company, its expiry date and when it was last used, never the whole key.

A key is a password

Anyone who has the key acts in To Bill in your name. Do not put it in an email, a shared document or a code repository. A lost key is revoked straight away (see below) and replaced with a new one.

Send the key ​

Each request carries the key in the HTTP Authorization header, as a Bearer token:

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

Claude Code with a key ​

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

What a key opens and what it does not ​

  • With Read only, the key only reads: any change is refused.
  • With Read and modify, it does what you can do in the company, with the same checks as the app, and never more than the rights of your role.
  • It does not open the sign-in to your account, the subscription, payments, the management of connections and keys, another company or a fiduciary’s cockpit.
  • Every change made with the key is recorded in the company’s activity under the name you gave it.
  • To Bill limits the number of requests per minute and per key; beyond that, it refuses requests for a while and the tool must wait before trying again.

Revoke a key ​

In Settings › AI and API connections, click Revoke next to the key, then confirm. It stops working straight away. A key that has expired stays in the list, marked Expired, until you revoke it.