Usage of the public / signature key system (old api authentication)

Einleitung

It is generally advised to use the OAuth 2.0 authentication. The public / signature key authentication was used before the implementation of the OAuth 2.0 interface.

API url

The base url is built by using the following template:

https://office.bexio.com/api2.php/%company_id%/%user_id%/%public_key%

The placeholders must be replaced with the following values:

company_id
The identifier for your company. You can find your company_id in the bexio API settings.
user_id
The ID of a user in your account. Please contact the bexio-support if you do not know this ID.
public_key
The public key. You are able to generate public keys in the bexio API settings

Combining these placeholders may result in a URL like the following: https://office.bexio.com/api2.php/abc/1/c8aa6dc63caa8181e58a50427b873c51

Signature

The danger of manipulated data (e.g. man-in-the-middle attack) is mitigated by generating a signature for each request. For this purpose, the client creates a hash value by using a few parameters of the request and a secret signature key. The server will create the same hash and will compare the two hash values.

The signature is built by using the following values:

md5(Method + URL + POST data (payload) + Signature key)

Please note that the method must always be written in lowercase. If the request is using a POST method, you have to provide the value post.

Example

A contact with the ID 3 will be modified by setting a new first name. This happens with the following request:

POST /api2.php/test/1/f061894d0992d8f137ade0cc45206428/contact/3 HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)
Host: office.bexio.com
Accept: application/json
Signature: 0c6d031c048794d04b14ffab3b87c9d7
Content-Length: 21
Content-Type: application/x-www-form-urlencoded

{"name_2":"Samantha"}

This will result in the following signature:

Placeholder Value
Method post
URL https://office.bexio.com/api2.php/test/1/f061894d0992d8f137ade0cc45206428/contact/3
POST data (only needed if available) {"name_2":"Samantha"}
Signature key 6363d622375dd5261c8e2e4486a12dd8

By concatenating these values we will receive the following string:

posthttps://office.bexio.com/api2.php/test/1/f061894d0992d8f137ade0cc45206428/contact/3{"name_2":"Samantha"}6363d622375dd5261c8e2e4486a12dd8

Generating a md5-Hash of this string (e.g. by using http://www.functions-online.com/md5.html) will result in the following signature:

0c6d031c048794d04b14ffab3b87c9d7