In order to embed Withings WebViews, the partner must be able to set up a server that will host at least the following web services used by your mobile application or Withings servers:
- User Creation web service: called by your application on your server. This web services needs to call the Withings User Creation API (refer to this section for more information).
- Token Management web service: called by your application on your server. This web services needs to fetch fresh tokens from Withings and render them to your application on-demand when the end user wants to manage his devices (refer to this section for more information).
User Creation API
In order to use the Withings devices, a Withings account is required. You will need to use the User Creation API to create a Withings account. This web service returns valid API tokens so your application is able to open the WebViews (installation and device settings WebViews)
The base URL for the User Creation API is:
The base URL for the User Creation API on the HIPAA Cloud is:
The following table specifies the
POST parameters the partner must set to call the User Creation API.
|string||yes||Service action name. Must take the string value |
|string||yes||Client id available here or here for HIPAA and HDS Cloud.|
|string||yes||A random token used to prevent replay attacks (Cf. Signature v2 - Getnonce)|
|string||yes||Hash of params (see Signature hash protocol).|
|boolean||yes||Specifies if customer accepted Withings commercial contacts. Possible values are: |
|integer||yes||Unix timestamp of user's birthdate|
|json||yes||End user height and weight measures (refer to Measure model)|
|integer||yes||End user gender. Possible values are: |
|local_code||yes||End user language preferences. Possible values are listed below|
|json||yes||End user unit preferences (refer to Unit model)|
|timezone||yes||End user timezone using the TZ database name (Ex: |
|yes||End user email that will be used to create Withings partner account.|
|string||yes||End user shortname (used on the scale device screen when a user is selected). Shortname must respect the following regex: |
|string||yes||Partner end-user unique identifier.|
|string||no||End-user lastname (if not set, will take the same value as shortname).|
|string||no||End user firstname (if not set, will take the same value as shortname).|
|string||no||Phone number in E.164 format. End user will receive a verification code on this phone number for 2 factor authentication if they wish to securely access the data of their program in the Withings app in the future (recommended)|
|string||no||Recovery code can be used by end user as a 2nd authentication factor in the Withings app if they wish to securely access the data of their program in the future. You will be responsible of securely providing this recovery code to your user if he asks for it.|
|json||no||End user goals for daily step or sleep (refer to Goals model)|
nonce parameter has to be generated each the web service is called to prevent replay attacks. Get more information here
POST body should be encoded using
The reponse of the web services is the following one:
To generate the API tokens (access_token, refresh_token, csrf_token), the web service OAuth 2.0 - Get your access token needs to be used with the
code that is rendered in the reponse of the User Creation call.
To get more information on possible status values, please refer here.
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:
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
sha256and your partner's
client_secret(available in your Withings partner dashboard) as a secret key.
- Add the hash string in the parameters under the
- Refer to the following complete example to see how to generate a hash signature.
Example of signature generation in
Token Management API
Once you have generated the first API tokens after the end-user User Creation, you need to manage the API tokens and refresh them when required or when your mobile app is requesting fresh tokens using the web service OAuth 2.0 - Refresh your access token.