Each API call has to be authenticated. We describe in this section the different ways to authenticate. These Authentications are used in conjunction with HTTPS.

 Stay on track with our changelog

If you want to be notified when our team plan/release some new technical features or if you use our API and you want to make sure our new feature won't break your code, we advise you to subscribe to the changelog channel.

 

Summary

Basic Auth

In the context of an HTTP transaction, basic access authentication is a method for an HTTP user agent to provide a user name and password when making a request.

The user has the same access as if he/she was connected using the web application.

This is best suited for testing purposes. We don't recommend using hard coded credentials in a script or application.

The ability to use BasicAuth for API calls, has to be activated:

  • at https://ui.boondmanager.com/administrator/developer/apisandbox

FireShot_Capture_113_-_Espace_d_veloppeur_-_mbe.wishgroupe.com.png

  • at http://ui.boondmanager/administrator/my-profile

FireShot_Capture_116_-_Compte_administrateur_-_mbe.wishgroupe.com.png

The Authorization field is constructed as follows:

  • The username and password of a BoondManager account separated by a colon ':'
  • The resulting string is encoded into Base64 following RFC3548
  • The authorization method, "Basic", and a space is then put before the encoded string

Example:

Using test@domain.tld as username and test as password the header would be:

Authorization: Basic dGVzdEBkb21haW4udGxkOnRlc3Q=

 

Client token

For this authentication, the structure of the header is the same as the previous section. The differences are:

  • The header's name: here it is X-Jwt-Client-Boondmanager
  • The client's key and the client's key can be found at this URL https://ui.boondmanager.com/administrator/developer/apisandbox
  • client's token replaces the App's token.
    {
    "userToken": "token1",
    "clientToken": "token2",
    "time": 1528535249,
    "mode": "normal"
    }
  • The client's key will be used as a secret for the hash algorithm.
  • Just in case you missed the previous section ;), the user's token is retrievable from either:
    • decoding the signedRequest received from your App
    • an administrator's dashboard > Security section > User's token
    • a user's account > Configuration > Settings > Security > User's token
  • The ability to use X-Jwt-Client-Boondmanager for API calls, has to be activated:

    • in your administration console's dashboard, section Security. 
    • a user's account > Configuration > Settings > Security > User's token

The client's token and client's key are retrievable from the administrator's dashboard.

App token

An App's token is a JWT(JSON Web Tokens) token. It can be used to prove access rights to use our API.

This is the standard way of authentication from an App.

Requests to our servers have to send a header X-Jwt-App-Boondmanager that is constructed as follows:

  • A header, encoded into Base64, consisting of 2 parts :
    • The type of token, which is JWT
    • The hashing algorithm being used. Currently, BoondManager only supports HS256:
{
"alg": "HS256",
"type": "JWT"
}
 
  • A payload, encoded in Base64, consisting of 4 parts :
    • The user's token is retrievable from either:
      • decoding the signedRequest received from your App
      • an administrator's dashboard > Security section > User's token
      • a user's account > Configuration > Settings > Security > User's token
    • The App's token received during the installation process
    • The time of the request as a UNIX timestamp
    • A mode indicating we will be checking the user's rights. Possible values are:
      • "normal": we will check the user's current rights
      • "god": we will not check the user's right's and assume his has total access to the data. Please use it only for users who have Manager access. Some endpoints are only accessible in this mode: /contracts,  /advantages, /absences, /times and /expenses. This mode will not override restrictions placed on accessible APIs when creating the APP.
{
"userToken": "token1",
"appToken": "token2",
"time": 1528535249,
"mode": "normal"
}
  • At last, a signature using the header and payload we described:
    • The header encoded into Base64
    • The payload encoded into Base64
    • A hash using the specified algorithm declared in the header (here HS256) using the App's key as a secret. Note that this key is retrievable from the App's page which is accessible from an administrator account:
      • an administrator's dashboard > Apps
HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload),appKey)

If we apply this algorithm to the values we used as examples, the header's value would be: 

X-Jwt-App-Boondmanager: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyVG9rZW4iOiJ0b2tlbjEiLCJhcHBUb2tlbiI6InRva2VuMiIsInRpbWUiOjE1Mjg1MzUyNDksIm1vZGUiOiJub3JtYWwifQ.T8hF1MqFO5sMpTdqnMhWcb1gXWpWuLWFlc6XxZN6_h8

 

Building the token

Here is a PHP snippet that will allow to build either X-Jwt-Client-Boondmanager or X-Jwt-App-Boondmanager.

As we saw, the header's value is the concatenation of 3 values separated by a dot '.':

function buildJWTClient() {
$payload = [
"userToken" => USER_TOKEN,
"clientToken" => CLIENT_TOKEN,
"time" => time(),
"mode" => "normal" //or "god"
];
return jwtEncode($payload, CLIENT_KEY);
}

function buildJWTApp() {
$payload = [
"userToken" => USER_TOKEN,
"appToken" => APP_TOKEN,
"time" => time(),
"mode" => "normal" //or "god"
];
return jwtEncode($payload, APP_KEY);
}

function jwtEncode($payload, $key){
$header = ['typ' => 'JWT', 'alg' => 'HS256'];
$segments = [];
$segments[] = base64UrlEncode(json_encode($header));
$segments[] = base64UrlEncode(json_encode($payload));
$signing_input = implode('.', $segments);
$signature = hash_hmac('SHA256', $signing_input, $key, true);
$segments[] = base64UrlEncode($signature);
return implode('.', $segments);
}

function base64UrlEncode($input) {
return str_replace('=', '', strtr(base64_encode($input), '+/', '-_'));
}

You can find an implementation of these same functions in our example App here

 

 

Nous espérons que cet article vous a été utile et nous vous invitons grandement à nous l'indiquer en votant juste en dessous.

S'il vous reste des questions sans réponse alors n'hésitez surtout pas à contacter notre service Support qui reste à votre écoute :

Contacter le support

Tel : (+33) 03 62 27 61 05

Boondmanager-Mascot-Desk-lg.png

Was this article helpful?
3 out of 5 found this helpful

Comments

0 comments

Article is closed for comments.