Authentication

Signature hash protocol

In order to authenticate a partner, some Withings APIs use a hash value as a signature. The signature consists of the following parameters:

  • action
  • client_id
  • nonce

To generate a signature please follow these steps:

  • Generate a valid nonce using the service Signature v2 - Getnonce
  • Sort the values alphabetically by key name: action -> client_id -> nonce
  • Generate a string by concatenating values separated by a comma. The string should look this this: value1,value2,value3.
  • Apply an hmac hashing function on the string using the algorithm sha256 and your partner's client_secret (available in your Withings partner dashboard) as a secret key.
  • Add the hash string in the parameters under the signature key.

Example

Example of signature generation in PHP language:

<?php
$client_secret = 'My Partner Registration Client Secret';
$client_id = 'My Partner Registration Client Id';
$nonce = 'The nonce I retrieved using service: Signature v2 - Getnonce';
$signed_params = array(
'action' => 'activate',
'client_id' => $client_id,
'nonce' => $nonce,
);
ksort($signed_params);
$data = implode(",", $signed_params);
$signature = hash_hmac('sha256', $data, $client_secret);
$call_post_params = array(
// Set the generated signature
'signature' => $signature,
// Set the signed parameters as clear text in the call post parameters
'action' => 'activate',
'client_id' => $client_id,
'nonce' => $nonce,
// Set other parameters requested to call the service (here we are calling "User v2 - Activate")
'redirect_uri' => 'https://www.withings.com',
'birthdate' => 1563746400
// [...]
);
// Then call the service by using the $call_post_params array as post parameters
?>

Token reception

This section on token reception relates to the following services:

To avoid collisions with existing Withings consumer accounts, these three services create a new end user account in the partner API namespace.

  • The service will synchronously render the authorisation code and thestate and external_id input parameters in the call response.
  • The partner will then need to fetch the access and refresh tokens using the token service as described in the second step of the OAuth 2.0 application flow.
  • If the end user account already exists in the partner API namespace when the service is called, a new account is not created and the authorisation code to access credentials for the existing account will be returned.
Help

Login required

Please login in order to file a request. If you did not create a developer account yet, you can create one by clicking the Signup button.

OK