bexio API (3.0.0)

The bexio API uses HTTPS methods and RESTful endpoints to create, edit, and manage documents in the bexio system. JSON is used as the data interchange format.

In order to use the bexio API, you need to follow the following steps in order:

1. Create a bexio account by signing up for a trial account at https://www.bexio.com and complete the onboarding process. If you already have a bexio account, you can skip this step.
2. Go to the developer portal at https://developer.bexio.com and log in using your bexio credentials.
3. Read and accept the terms and conditions
4. Create a new app and make sure that you define a valid site for the "Allowed redirect URL" field(s)
5. By clicking on the section "App Details" you can reveal the Client ID and Client Secret
6. Initiate the Authorization Code Flow to obtain an access token.
7. Use the access token to create a request to the bexio API. The example below fetches a list of contacts (make sure to request the scope contact_show in the authorization code flow)

curl -X GET \
      https://api.bexio.com/2.0/contact \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'

Make sure to replace {access-token} with the token you received in Step 6.

If you've encountered a bug, we're here to help. Before you begin, ensure you can reproduce the issue using a tool for testing APIs, such as Postman. To report the problem, please use the form provided below. Be sure to include detailed steps allowing us to reproduce the issue. However, do not include any credentials in your report.

Report a problem

Please do note that the API is provided as is based on this very documentation, there is no guided implementation or code support available.

We will list any changes to the current version of the API here.

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

bexio supports the "Authorization Code Grant" as defined in OAuth 2.0 RFC 6749, section 4.1 to obtain an Access Token. Your app must be server-side because during this exchange, you must also pass along your application's Client Secret, which must always be kept secure, and you will have to store it in your client.

How it works

1. The user clicks Login within the regular web application.
2. The web application redirects the user to the /authorize endpoint of the bexio OpenID Connect service.
3. The bexio OpenID Connect Service displays the login page.
4. The user authenticates and sees a consent page listing the permissions bexio will give to the web application.
5. The user is redirected back to the web application with an Authorization Code.
6. The web application sends this code to the bexio OpenID Connect service (/token endpoint) along with the application's Client ID and Client Secret.
7. bexio verifies the code, Client ID, and Client Secret.
8. An ID Token and Access Token (and optionally, a Refresh Token) is returned to the web application.
9. The web application uses the Access Token to call the bexio API.
10. The bexio API responds with requested data.

Code example (PHP)

The following example showcases the usage of OpenID Connect (PHP example uses the OpenID-Connect-PHP library). The library uses OpenID Connect Discovery to automatically configure the application.

<?php
require __DIR__ . '/vendor/autoload.php';
use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient("https://auth.bexio.com/realms/bexio", "client_id", "client_secret");
$oidc->setRedirectURL("https://www.example.com/oidc_callback");
$oidc->addScope(array("openid", "profile", "contact_show", "offline_access"));
$oidc->authenticate();

echo $oidc->getAccessToken();

The consent screen shown to the user will look like this:

The scope offline_access is required to obtain a refresh token to keep the api connection alive.

1. POST a request to the endpoint “/token”. Make sure you use the grant type “refresh_token”. This is implemented according to the standards of OAuth 2.0 RFC 6749
2. The response contains a new access token. Please note that the requested scopes do not change when refreshing a token. Acquiring new scopes is only possible by going through the initial authorization process again.
3. The new access token can be used to authorize requests and execute API requests
4. The bexio API responds with the requested data.

Redirect URLs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application with either an authorization code or access token in the URL. Because the redirect URL will contain sensitive information, it is critical that the service doesn’t redirect the user to arbitrary locations.

The best way to ensure the user will only be directed to appropriate locations is to require the developer to register one or more redirect URLs when they create the application.

Source https://www.oauth.com/oauth2-servers/redirect-uris/

The new bexio API platform requires to define redirect URLs during the app registration in the developer portal. Unknown URLs will not be accepted during the Authorization and the user will receive an error message.

Up to 10 different redirect URLs can be defined for an app, e.g. to support multiple test environments and mobile apps with custom schemes

In its compact form, JSON Web Tokens consist of three parts separated by dots (.), which are:

• Header
• Payload
• Signature

Therefore, a JWT typically looks like the following: xxxxx.yyyyy.zzzzz

JWT Payload

A typical access token (JWT) looks like the following:

{
  "sub": "620603d3-4221-46e5-a109-47b492e691b8", #this is a unique user identifier (format UUID)
  "login_id": "620603d3-4221-46e5-a109-47b492e691b8", #this is a unique user identifier (format UUID)
  "company_id": "4ubk32lc2ss0", #this is a unique company identifier
  "azp": "8ad0e25d-1e8d-47c1-8613-8a28a9bee452", #this is the client ID of the app (format UUID)
  "scope": "openid contact_edit offline_access", #the requested scope
  "iss": "https://auth.bexio.com/realms/bexio", #the issuer of the token
  "exp": 1574882663, #the expiration date of the token
  "iat": 1574868263, #the date on which the token was issued
  "user_id": 7295, #legacy user id, please use the uuid in the field "login_id"
  "company_user_id": 1, #legacy user id, please use the uuid in the field "login_id"
  "jti": "5ffe7bfc-cdd0-4c19-8e28-361891546045" #unique identifier for the JWT
}

As a user can be part of multiple companies (bexio accounts), using the login_id to identify the user is not enough. A combination of the fields company_id and login_id can be used to uniquely identify a user that belongs to a bexio account.

As an example, the user Peter Smith (login_id 620603d3-4221-46e5-a109-47b492e691b8) belongs to the companies "Peter Smith Photography" (company_id 4ubk32lc2ss0) and "Peter Smith Video Productions" (company_id zk34nc55bc4f).

API Tokens are a simplified method of acquiring an access token, for those use cases where the OAuth flow will not work. Good examples of those are scripts running periodically in the background or development phase of any integration with bexio API.

Using an API Token is the easiest way to gain access to your own bexio data or that of a client of yours. The token is a unique code that grants access to the data and you need to manage these integrations on an individual basis. Personal API Tokens can be created by super admin users directly in bexio by visiting https://office.bexio.com/index.php/admin/apiTokens. The scope of access of the token is determined by the scope of the super admin’s access that creates the token. The token is valid almost indefinitely with a set validity period of 50 years.

To use a Personal API Token to authorise a request, it must be added to the Authorization header of every request:

Authorization: Bearer eyJraWQiOiI2ZGM2YmJlOC1iMjZjLTExZTgtOGUwZC0w...

Each API endpoint is available on our API host https://api.bexio.com.

Endpoints are usually defined with a relative path, as seen in the following example:

Each relative path must be combined with the API platform URL. For the example this would result in the endpoint https://api.bexio.com/2.0/contact

Where possible, bexio tries to use the appropriate HTTP verb for its operations

HTTP headers let the client and the server pass additional information with an HTTP request or response. An HTTP header consists of its case-insensitive name followed by a colon (:), then by its value.

Request Headers

The following headers must be used for every request:

• Accept: application/json
• Authorization: Bearer <token>

Additionally, the header Content-Length: <length> must be specified for requests with a payload.

Response Headers

The API will always indicate the return type with a Content-Type header. Normally the header value is set to application/json, but can vary (e.g. for PDF exports).

Response Codes Actions and errors yield different HTTP response codes. Please have a look at the expected response codes in the following list:

Error responses contain an HTTP status code and a JSON response body that is structured as follows:

{
    "error_code": 404,
    "message": "Page not found"
}

Some older endpoints implement search methods. Searching for these endpoint works by sending a POST request to the resource (e.g.: POST /contact/search or POST /country/search). The search parameters must be provided in the body of the POST request.

Please have a look at the resource documentation to see a list of available search parameters.

Criterias

You can use different criterias for the search. The criteria “like” will be used by default if you do not define a criteria.

Code example (PHP)

The following example shows how the search for the contacts API can be used. The last name of the contact must be “Meyer” and the contact number must be greater than 10.

Define the search array

$data = array(
  array(
    'field' => 'name_1',
    'value' => 'Meyer',
    'criteria' => '=',
  ),
  array(
    'field' => 'nr',
    'value' => 10,
    'criteria' => '>',
  ),
);

Transform the array to JSON

json_encode($data);

POST-Body for the search

[
  {
    "field" : "name_1",
    "value" : "Meyer",
    "criteria" : "="
  },
  {
    "field" : "nr",
    "value" : 10,
    "criteria" : ">"
  }
]

The bexio API enforces a rate limit that limits the number of requests a company can make per minute.

If this limit is reached, the API will return a 429 status code to the client.

HTTP Headers

The table below describes the relevant headers regarding the API rate-limit.

Is an OpenAPI (Swagger) definition available?

No, we currently do not provide an OpenAPI definition but we have plans to put it online.

Why is “insert business process here” not available as an API endpoint?

We are continously working on a product that makes our customers more successful. Unfortunately we are not able to support every use case via API yet.

Are Credit Notes available?

No, currently Credit Notes are not available but we have plans to put it online.