Strainovic IT

Create a bexio API token

Anyone looking for a “bexio API key” will not find a button for it in bexio itself. Today there are two ways to access the bexio API: a personal access token for your own scripts, or an app in the Developer Portal that signs in via OAuth 2. This guide shows both, the first call with the token and the mistakes that usually stop people at the start.

Flow: a token is created in the Developer Portal, your script sends it in the header, api.bexio.com returns the datadeveloper.bexio.comCreate a personaltoken or an appYour scriptToken in the header“Authorization:Bearer”api.bexio.comContacts, invoices,items as JSONFlow: a token is created in the Developer Portal, your script sends it in the header, api.bexio.com returns the datadeveloper.bexio.comCreate a personal token or an appYour scriptToken in the header “Authorization:Bearer”api.bexio.comContacts, invoices, items as JSON

Is there a bexio API key?

No, not any more. The documentation used to describe fixed “API Tokens” for server-to-server connections. In October 2024 bexio replaced that section with Personal Access Tokens, PAT for short. Older guides that promise a permanent key from the settings are therefore out of date.

Today every request to https://api.bexio.com needs an access token in the header Authorization: Bearer …. Where the token comes from depends on who uses the connection:

  • Only you, for example for a script, an export or a test: personal access token (way 1).
  • An application for others, for example a plugin on a website or a service for several companies: an app in the Developer Portal with OAuth 2 (way 2).

The reference for all endpoints is at docs.bexio.com. To try things out without real accounting data, bexio offers a trial account that you open on bexio.com.

Way 1: create a Personal Access Token

  1. Open developer.bexio.com/pat and sign in with your bexio account.
  2. Create a new token and store it somewhere safe straight away, for example in a password manager or a file only you can read.
  3. Send the token from your script as a bearer token.

According to the documentation, a PAT works like this:

  • Full access: a PAT has all default scopes and therefore access to all of the company’s data. Whoever knows it can read invoices and change contacts.
  • Valid for 60 days: after that it has expired and the script needs a new one.
  • Revoked by deleting it: a deleted token can no longer be used. It may take up to one hour until the revocation takes full effect.
  • For personal use only: if you want to restrict the rights, for example to reading contacts, use an app instead.

Test the token

The simplest test is a list of contacts:

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

If a JSON list comes back, access works. The API reports errors with an HTTP status code and a short JSON body with error_code and message. A call to /3.0/users/me also shows which user the token acts as. That matters, because the API never has more rights than this user has in bexio.

The token never belongs in a public Git repository, in JavaScript in the browser or in an email. If it has been exposed anyway: delete it in the Developer Portal and create a new one.

Way 2: an app in the Developer Portal with OAuth 2

For anything that other people or companies connect, a PAT is the wrong tool. Then you need an app of your own:

  1. Sign in to the Developer Portal and accept the terms of use. bexio points in particular to section 4.4 on commercial use.
  2. Create an app and enter the allowed redirect URLs, the addresses bexio sends the user back to after signing in.
  3. Read the client ID and client secret under “App Details”. The secret stays on the server.
  4. Let the user sign in via the “Authorization Code Flow” on auth.bexio.com. There they see which rights the app asks for and confirm them.

These rights are called scopes, for example contact_show for reading contacts or kb_invoice_edit for editing invoices. A write scope includes read access. With the scope offline_access the app also receives a refresh token, which it uses to get new access tokens without the user signing in again. The guide connect the bexio API to WordPress shows what this looks like in WordPress.

Which way fits?

QuestionPersonal Access TokenApp with OAuth 2
Who uses the connection?you yourselfother users or companies
Rightsall of the company’s dataonly the requested scopes
Validity60 daysas long as the refresh token is renewed regularly
Efforta few minutessign-in, token storage, renewal
Typical useexport, test, own scriptplugin, integration, service

Common mistakes

  • Expired token: a script that ran for two months suddenly fails. Usually the PAT has expired after 60 days.
  • Missing user rights: the API works with the rights of the user who created the token or connected the app. If that user has no access to contacts in bexio, the right scope does not help either.
  • New scopes on renewal: renewing a token keeps the same rights. If the app needs more, the user has to sign in again.
  • Redirect URL does not match: if the address is not entered exactly like this in the app, sign-in stops with an error message.
  • Too many requests: the API limits requests per minute and company. When the limit is reached, it returns status 429; the headers RateLimit-Remaining and RateLimit-Reset tell you how long to wait.
  • No OpenAPI file: according to its own documentation, bexio does not provide an OpenAPI description. You cannot generate a client automatically but write it from the reference.
  • Outage rather than error: if the API does not respond at all, check the status page bexio-status.com before searching your own code.

Ready-made solutions

If you would rather not manage a token yourself, there is a ready-made connection for the most common cases:

  • bexio form connector: WordPress plugin, enquiries from the website form become contacts with a note in bexio. You connect with one click on “Connect to bexio”, without an app of your own and without a token someone has to renew every 60 days.
  • Connect the bexio API to WordPress: the way with your own app, step by step, if you build it yourself.

All guides