API Docs
Request access

OAuth

Introduction

The bexio API supports the authorization framework OAuth 2.0. External applications can apply for access to an account without having to know the login credentials.

In order to use the OAuth interface, a client ID and a client secret is required. If you do not have either a client ID or a client secret, you can request access here.

Standard procedure

You need to execute the following five steps to create an API request:

  1. Request access to the bexio account
  2. bexio redirects the user to the authorization page
  3. Request an access token
  4. Receive the access token
  5. Call any resource

1. Request access to the bexio account

GET https://office.bexio.com/oauth/authorize

Parameter

client_id
Required string - The client id you have received from the bexio support.
redirect_uri
Required string - The user will be redirect to this url after the authorization.
state
Required string - A random sequence. Should be used as a protection against CSRF-Attacks.
scope
Optional string - A whitespace-separated list of scopes.

2. bexio redirects the user to the authorization page

The User needs to login.

OAuth-Login

Once the user is logged in, he can check the requested scopes. The user is able to remove scopes if he does not want to share the information. Please consider this in your implementation.

Anforderung von Ressourcen

If the user confirms the authorization request, he will be redirected back to the previously defined redirect_uri. bexio will add the GET parameter code to this redirect_uri. This code is only valid for a few seconds and can be used to request an access token (see step 3).

3. Request an access token

You can request an access token by using the code you have received during step 2.

POST https://office.bexio.com/oauth/access_token

Parameter

client_id
Required string - The client id you have received from the bexio support.
redirect_uri
Required string - The same redirect uri as in step 1
client_secret
Required string - The client secret you have received from the bexio support.
code
Required string - The code you have received during step 2.

4. Receive the access token

Once you have requested the access token you will receive the following JSON response from bexio

{
  "access_token": "da96469ea968dd7489d5e395d07578b94c45c732",
  "expires_in": 14400,
  "token_type": "bearer",
  "scope": "contact_show general",
  "refresh_token": "6af54fda928c6d21902393f0ea246c2a91ce08b8$aI0qlqicUsnk+LnUZ84m486QdN1t2eCZRlsaTlDsCFI=",
  "org": "mycompany",
  "user_id": 1
}

The access token is valid for a limited time. The lifetime of the token can be learned from the value of expires_in. In this case, the access token is valid for 14400 seconds -> 4 hours. The value refresh_token (valid for 2 weeks) can be used to request a new access token.

The field org represents the company identifier and must be used for every request. The field user_id is the user ID of the authorized user.

5. Call any resource

Any request has the following structure:

base url + resource

The base url is https://office.bexio.com/api2.php/%org%. Please note that %org% is a placeholder for the company identifier you have received in step 4. This would result in the following url to fetch a list of all taxes:

GET https://office.bexio.com/api2.php/mycompany/tax

The access token you have received in step 4 must be used in the Header Authorization. Please use the header like this: Authorization: Bearer %access_token%. In addition you must add an Accept header to the call. This results in the following headers:

Accept: application/json
Authorization: Bearer da96469ea968dd7489d5e395d07578b94c45c732

Refresh the access token by using the refresh token

If the access token has expired, a new access token can be acquired by using the refresh token.

POST https://office.bexio.com/oauth/refresh_token

Parameter

client_id
Required string - The client id you have received from the bexio support.
client_secret
Required string - The client secret you have received from the bexio support.
refresh_token
Required string - The refresh token you have received during step 4

Response

You will receive the same response as in step 4. Please note that the values access_token and refresh_token are different. Once you have requested a new access token, the old refresh token will no longer be valid.

{
  "access_token": "c0d8b09a3d6867d31cbba64a3d5574a69eda9238",
  "expires_in": 14400,
  "token_type": "bearer",
  "scope": "contact_show general",
  "refresh_token": "461690a37d06d0b994b008805ac1df025bbe72d8$aI0qlqicUsnk+LnUZ84m486QdN1t2eCZRlsaTlDsCFI=",
  "org": "mycompany",
  "user_id": 1
}