Withings API developer documentation

Any question ? contact our support platform

First steps

Because Withings may not provide a client library for your language of choice, you may have to implement the authentication part. Those first steps will guide you through the authentication part of the API into making the first user data request.
In order to use the API, you will need to register as a developper here to get a consumer key and secret. Note that you will also need to have an end-user Withings account to fetch data from.

Withings API uses oAuth v1 for request signing with hmac-sha1 hashing algorithm. This algorithm basically consists in creating a signature by hashing all the request information (called the request "base string"), mixed with a secret that only you and withings know. This secret is composed of your consumer key and the access token (when relevant).
Also, "nonce" and "timestamp" parameters are added to make sure every request is unique in order to prevent replay attacks.
The full oAuth specification regarding request signing is accessible here. Specifically, you may want to see this example on how to build the "base string".

For each step, you will be asked to enter some information, then press a button to generate the HTTP request to send to the API by clicking on the link. That request includes every parameters including oAuth signature. A detailed log of all the intermediate actions performed to create the request will also be displayed. Note that each step reuses fields entered on previous steps, so you need to fill information for step 1 and 2 to be able to perform step 3.

Step 1 : get a oAuth "request token"

This token will later be used to ask a user to allow your system to access his data using the Withings API. You need to do this step only once per user.
Note that the request token/secret pair is not used in the data access requests (step 4). It is only used to create the authorization request (step 2) and to generate the access token (step 3). Note that this token expires after two minutes.

Please enter the following information so that we can generate the http request you will have to perform to get a request token/secret pair.

Log :

                    Result (click to perform request) : 

Step 2 : End-user authorization

For your system to be able to access an end-user data, he should allow it to do so. For that, you need to present him a special URL signed using the request token secret generated on step 1 appended to your consumer secret (separated by an &). This URL will redirect him to the Withings web site where he will allow your application to access his data. Then, once the user authorizes your system, he will be redirected to the callback URL provided in step 1 and associated to this request token.

Please enter the following information, retrieved from step 1 response :

Log :

                    Result (click to allow your account to access your data. You will need to log in as a Withings end-user) : 

Step 3 : Generating access token

Now that your account has been authorized by the user to access his data, you can generate an access token / secret pair that will be used to query the rest of the api in order to fetch data for this user. In a real world system, this pair will be stored along with the other user information.
Note that this step uses the request token generated on step 1, which has a 2 minutes lifespan.

Please enter the following information, retrieved from step 2 callback :

Log :

                    Result (click to perform request) : 

Step 4 : Access User Data

You can now use the Withings API for this user, using the access token generated on step 3. See the reference for all the APIs exposed by Withings.

Please enter the following information, retrieved in step 3 :

Log :

                    Result (click to perform request) : 

Next

You should now be able to use the Withings API for your users. Please see the reference for detailed information on API accepted parameters and return values.