Showcase / Campus authentication

If you use DoYouBuzz Showcase or DoYouBuzz Campus, you can access the datas of your application, users and CV with this this API.

API keys

API keys are managed by an administrator of your Showcase / Campus account, under Settings, then API. From that page you can create as many keys as you need, and revoke them at any time.

Each key is made of two values:

When creating a key you choose its lifetime: unlimited, 30, 90 or 365 days. An expired or revoked key is refused exactly like an unknown one.

The API consumption page of the same settings section shows your traffic, your rate limits and the calls that have been rejected, per key and per endpoint.

How to access protected resources

GET | PUT | POST | DELETE https://showcase.doyoubuzz.com/api/v1/<method>?apikey=:apikey&timestamp=:timestamp&nonce=:nonce&hash=:hash

Mandatory parameters

There are a few mandatory parameters for each request made to the Showcase API :

How to compute the hash parameter?

The hash is an HMAC SHA-256 of a canonical representation of your request, keyed with your secret. Because the HTTP method and the path are part of what you sign, a signed URL cannot be replayed on another endpoint.

In plain english

1. Build the canonical string: three lines joined by a line feed (\n).
   1. The HTTP method, in upper case: GET, POST, PUT or DELETE.
   2. The path of the request, and nothing else: no scheme, no host, no query string. For https://showcase.doyoubuzz.com/api/v1/users/666?apikey=… the path is /api/v1/users/666.
   3. The query parameters: take all the parameters you send in the URL (both mandatory and optional) except hash, sort them by parameter name, encode both the name and the value with a RFC 3986 encoding (rawurlencode() in PHP, encodeURIComponent() in JavaScript), write them as name=value and join them with &. A parameter holding an array must be JSON encoded before being URL encoded.
2. Compute the HMAC SHA-256 of that string, using your secret as the key, and send the hexadecimal digest as the hash parameter.

PHP function

This function takes the HTTP method, the path of the request, an associative array of the parameters to send, and the secret of your key. It returns the parameters with the computed hash added :

function computeHash($method, $pathInfo, $params, $apiSecret)
{
    unset($params['hash']);
    ksort($params);

    $pairs = array();
    foreach ($params as $paramKey => $paramVal) {
        if (is_array($paramVal)) {
            $paramVal = json_encode($paramVal);
        }
        $pairs[] = rawurlencode($paramKey) . '=' . rawurlencode($paramVal);
    }

    $canonical = strtoupper($method) . "\n" . $pathInfo . "\n" . implode('&', $pairs);

    return array_merge($params, array('hash' => hash_hmac('sha256', $canonical, $apiSecret)));
}

Example

Let's say you want to get the user with the id 666. According to the documentation you need to send a GET to https://showcase.doyoubuzz.com/api/v1/users/666 with these parameters :

So, let's compute the hash!

1. First, build the canonical string. The method is GET, the path is /api/v1/users/666, and the parameters sorted by name give apikey=shw_live_3f9a1c74be2058d6a1f4c39e7b0d82f4&nonce=7b1f4c9a2e8d6035&timestamp=1774267200 (none of these values needs to be escaped). Joined by line feeds, the canonical string is :

   GET
   /api/v1/users/666
   apikey=shw_live_3f9a1c74be2058d6a1f4c39e7b0d82f4&nonce=7b1f4c9a2e8d6035&timestamp=1774267200

2. Then compute the HMAC SHA-256 of that string with your secret as the key. Here the secret is c4e1a9f7b2d85630fa47e91c8b0d2356e7f1a4c980b3d62e5f8a17c4b9d0e236, and you get your hash parameter : be49e8c3daffdfe07b90fd1ee47f3062960f82bba4238b2ec244fbbacc63d621

Now, you can send the request to the API :

GET https://showcase.doyoubuzz.com/api/v1/users/666?apikey=shw_live_3f9a1c74be2058d6a1f4c39e7b0d82f4&timestamp=1774267200&nonce=7b1f4c9a2e8d6035&hash=be49e8c3daffdfe07b90fd1ee47f3062960f82bba4238b2ec244fbbacc63d621

Authentication errors

Every authentication problem is answered with a 403, whatever its cause: missing parameter, unknown / revoked / expired key, timestamp out of the 5 minutes window, wrong signature, or reused nonce.

For security reasons, an unknown key, a revoked key and an expired key all share the very same message ("This api key is not valid!"), so you cannot tell them apart from the response. If you get a 403 while your signature code is known to work, check the state of your key in the settings page.

Note that the body of a 403 is a plain error response, it does not use the JSON envelope of the 429 described in the rate limiting page.

Legacy keys

This section only concerns the API keys created before the introduction of the key manager. They keep working, unchanged, with the historical signature scheme: no nonce, and a MD5 signature. If you are integrating the API today, or if you created your key from the "API" settings page, use the HMAC scheme described above instead.

How to compute the hash parameter?

In plain english function

1. Take all the parameters sent in the URL (both mandatory and optionals), order them by alphabetical order (according to their name), then concatenate their value.
2. Add the apiSecret at the end of the resulting string
3. MD5 the result: this is your hash

PHP Function

This function takes two parameters : an associative arrays of the parameters to send, and the apiSecret :

function computeHash($params, $apiSecret)
{
    $paramsStr = "";
    ksort($params);
    foreach ($params as $paramKey => $paramVal) {
        $paramsStr .= $paramVal;
    }
    $hash = md5($paramsStr . $apiSecret);
    return array_merge($params, array('hash' => $hash));
}

Example

Let's say you want to get the CV with the id 16546 (you have previously verified you can access this ressource). To do so, according to the documentation you need to send a GET to https://showcase.doyoubuzz.com/api/v1/dyb/cv/16546 with these parameters :

So, let's compute the hash!

1. First, order the parameters according to their name, then concatenate their value. You will have the following string : IuQSDLKQLSDK344590Li9871359021513.
2. Then, append your apiSecret at the end of this string (here the apiSecret is IuJyt42BnUiOlPM8FvB67tG. You will have the resulting string : IuQSDLKQLSDK344590Li9871359021513IuJyt42BnUiOlPM8FvB67tG.
3. Use this string to create a MD5, and you will have your hash parameter : 44f36e1dd04a10c0be21b2d8e880f22b

Now, you can send the request to the API :

GET https://showcase.doyoubuzz.com/api/v1/dyb/cv/16546?apikey=IuQSDLKQLSDK344590Li987&timestamp=1359021513&hash=44f36e1dd04a10c0be21b2d8e880f22b