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.

The IdP, currently available at idp.bexio.com, is about to be replaced by a new IdP available on auth.bexio.com. Like the idp.bexio.com, the new solution will implement the OAuth2 protocol with the OpenID connect extension which ensures compatibility for API clients.

During the migration period of six months, both idp.bexio.com and auth.bexio.com will be available for API clients to initiate the OAuth2 authorization code flow and to issue API access tokens. This will allow API clients to migrate to the new IdP at their own pace.

idp.bexio.com will be decommissioned on 31.03.2025.

How to migrate an API client to the new IdP?

Most client applications can migrate to the new IdP by just reconfiguring the URLs to initialize the authorization flow and to issue tokens. Depending on the framework in use, the URLs to change might differ but usually includes one or more of the following URLs:

Other configuration options like client_id, client_secret or scope do not need to be changed.

Are there any new features for client applications?

From a client perspective, there are some minor improvements that simplify the correct use of id and access tokens:

• Claims in id tokens are aligned with the /userinfo endpoint. Id tokens will contain the following claims if the according scope is requested:
  • scope: profile, claims: given_name, family_name, gender, locale
  • scope: email, claims: email, email_verified
• In addition, the following scope has been added to request access to company information in id tokens and the /userinfo endpoint:
  • scope: company_profile, claims: company_id, company_name, company_user_id

Are there breaking changes?

The new IdP differs in some of the claims provided by the access and id tokens returned by the /token endpoint and in some of the properties provided by the /userinfo endpoint. The breaking changes affect the following claims:

• iss - This claim identifies the issuer of the token and is currently "https://idp.bexio.com". With the switch to the new IdP the value will change to "https://auth.bexio.com/realms/bexio".
• sub - This claim identifies the user who granted the creation of the token. Currently, the claim equals to the user’s email address. The new IdP will instead return a UUID identifying the user within bexio equal to the login_id claim.
  • If you’re using the sub claim to identify the user, consider switching to the login_id claim before migrating to auth.bexio.com. login_id will be identical on both the old and the new IdP for a given user.
  • If you’re using the sub claim to get access to the user’s email address, consider to use the email claim instead. Please note that the claim is only available if the email scope has been granted to your client. Alternatively, you can use the /3.0/users/me endpoint (docs).
• locale - Contains the user’s default locale if the user grants access to the openid profile scope and is provided by the /userinfo endpoint. idp.bexio.com currently uses the non-compliant underscore to separate language code from country code (as in de_CH). auth.bexio.com will provide the locale in the OIDC compliant format using a hyphen (e.g. de-CH).
• shard_id - This claim will no longer be available.

Additionally, the following will change with the switch to the new IdP:

• Offline sessions will have an idle timeout of 1 year. An offline session is created if tokens are requested with the offline_access scope. The returned refresh token will be valid indefinitely but the associated offline session will be closed if not renewed within 1 year. This effectively means that tokens must be refreshed within 1 year.
• idp.bexio.com supports accepting some parameters to the /token endpoint as query parameters in the URL. This behavior is no longer supported in the new IdP and all parameters must be passed in the request body.
• In some cases, you may run into more strict CORS policies after switching to the new IdP. These issues can be mitigated by adding your web origin as a valid redirect URL for your app on https://developer.bexio.com. Redirect URLs will be accepted as valid web origins for requests from the according client.

Do users have to re-authorize my application after the switch?

To answer this question we have to distinguish between two cases:

• Applications using refresh tokens can migrate refresh tokens issued by idp.bexio.com to the new IdP by passing the tokens to the refresh token grant type on https://auth.bexio.com/realms/bexio. When the new IdP receives a refresh token issued by idp.bexio.com, the according user consent will be imported. This means that users wont be required to re-authorize your application in this case. Keep in mind though that this requires that applications replace refresh tokens with the new refresh tokens provided during the token refresh instead of reusing the refresh token received with the initial call to the token endpoint. Also, tokens have to be refreshed at least once before idp.bexio.com is decommissioned on 31.03.2025.
• If refresh tokens are not used, users will be required to give consent to the scope requested by your application again after switching to the new IdP.

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

Personal Access Tokens (PAT) can be managed on https://developer.bexio.com/pat and are convenient way to issue API access tokens for personal use:

• A PAT has all default scopes granted and therefore has full access to your company's data.
• A PAT is valid for six months after creation.
• A PAT can be revoked by deleting it on developer.bexio.com. After deletion, a PAT can no longer be used to access the API. In the worst case, it might take up to 1 hour until the revocation takes full effect. Subsystems might still be accessible by the token during this period.

If you have other requirements, like restricting the scope granted to a token, please use the Authorization Code Flow instead.

To use a PAT to authorise a request, it can be used as a bearer token in the Authorization header of a 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.