Skip to main content

OAuth web flow

API only integration - authentication flow

The OAuth 2.0 authentication application flow work as follows:

OAuth 2.0 flow overview
  1. Use Withings OAuth2 API authorize method to request app permissions to 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.

  2. Once the user has accepted your request, they are redirected to the URL your provided (see redirect_uri). An Authorization code parameter is added to this URL for you to rescue.

  3. Having this Authorization code, you get your access_token and refresh_token by using the requesttoken action on Withings OAuth2 API oauth2 webservice.

  4. When your access_token has expired, you can use your refresh_token to get a new access_token using the requesttoken action on Withings OAuth2 API oauth2 webservice.


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


Your application must ask for authorization to access information on a user's behalf. Scopes define the specific actions your application will be allowed to do on a user's behalf. Here is a list of scopes available, and the actions they allow :

Scope nameAllowed actionRelated webservices
user.activityGet data related to user physical activity and sleep activities.Measure v2 - Getactivity
Measure v2 - Getintradayactivity
Measure v2 - Getworkouts
Sleep v2 - Get
Sleep v2 - Getsummary
user.metricsGet data related to user ponctual measurements.Measure - Getmeas
Heart - Get
Heart - List
user.infoGet user personal data and allow link and unlink of user devices. This scope is intented for SDK integration only. Trying to use this scope without a contract with Withings will fail.User v2 - Get
User v2 - Link
User v2 - Unlink
user.sleepeventsScope used to receive notifications when sleep events happen.Bed in, bed out, inflate done notifications.

OAuth2.0 sample code

You can use this python sample code to help you implement the OAuth 2.0 application flow.

Demo user

A demo user is available to test the authentication flow.

To get access to the demo user's data, 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 authorization code and then the access_token and refresh_token.


Login required

Please log in to your Developer Dashboard in order to file a request.