Authentication

OAuth 2.0

For all Data API services, an authorisation token called an access_token is requested as an input parameter so that the Withings server can verify that the partner is allowed to access the user's data.

The access_token is retrieved once the user gives the partner permission to access their data. The access_token is always provided with a second token; the refresh_token. The refresh_token must only be used to request a new access_token once it has expired. When retrieving a new access_token, a refresh_token is also provided and you have to overwrite your current refresh_token with the new one.

For more information about the 2.0 authentication protocol, please refer to the RFC 6749.

Note for Cellular solutions and Withings Mobile SDK

Providers using Cellular solutions or the Withings Mobile SDK can skip building the authorisation URL as the access_token and refresh_token will be shared server side. Please refer to the Withings SDK documentation or the Cellular Activation API for more information about how to retrieve user tokens.

To start implementation, follow the OAuth 2.0 authentication application flow:

  1. Using the authorize method will request app permissions from the user. The authentication step will redirect the user to the Withings authentication page. The user will be able to sign up for a new account or sign in with their existing account. Refer to the service documentation to implement this step.
  2. Once the user accepts your request, they are redirected to your site with the Authentication Token in the URL. Refer to the service documentation to implement this step.
  3. If the code matches, you can get the access_token and refresh_token using the Authentication Token. This access_token is valid for three hours, so use refresh_token to get a new access_token after it expires. Refer to the service documentation to implement this step.

This diagram summarises the process:

Sample code

You can use one of our GitHub samples to help you implement the OAuth 2.0 application flow:

Demo user

A demo user is available to test the authentication flow.

During step one of the OAuth 2.0 application flow, you can use the optional parameter mode with the value demo. You will be redirected to the authorisation page and automatically logged in as a demo user. For a normal user, once you click the Accept button you will be able to retrieve the authorisation code and then the access_token and refresh_token.

Note: measures are generated every day and demo users will automatically be unlinked from your application after one day.

Example:

http://account.withings.com/oauth2_user/authorize2?response_type=code&client_id=XXXXX&state=a_random_value&scope=user.info,user.metrics,user.activity&redirect_uri=XXXX&mode=demo