Authorization URL
To use the Web Authorization Flow, you'll need to construct an authorization URL with the appropriate query parameters.
Here's an example of an authorization URL:
https://account.withings.com/oauth2_user/authorize2?response_type=code&client_id=YOUR_CLIENT_ID&scope=user.info,user.metrics,user.activity&redirect_uri=YOUR_REDIRECT_URI&state=YOUR_STATE
Replace YOUR_CLIENT_ID, YOUR_REDIRECT_URI, YOUR_STATE and the scopes with your actual values.
State Parameter
The state parameter acts as a CSRF protection mechanism by allowing you to include a unique string with your request.
This string is returned to your application when the user is redirected back to your callback URL. By comparing the original state with the returned value, you can ensure that the response hasn't been tampered with.
Additionally, the state parameter can carry context or session information, helping you track where the authorization request originated.
When someone navigates to this URL, they will be asked to authorize your application for the requested scopes.
Upon granting permissions, the user will be redirected to your specified redirect_uri, which will include an additional query string parameter called code. The state parameter will also be returned and should be validated at this point.
Please note that the authorization code is only valid for 30 seconds.
Scopes
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 name | Allowed action | Related webservices |
|---|---|---|
| user.activity | Get data related to user physical activity and sleep activities. Also required for notification management. | Measure v2 - Getactivity Measure v2 - Getintradayactivity Measure v2 - Getworkouts Sleep v2 - Get Sleep v2 - Getsummary Notify - Get Notify - List Notify - Update Notify - Revoke Notify - Subscribe |
| user.metrics | Get data related to user health measurements, heart recordings, stethoscope data, and user goals. Also required for notification management. | Measure - Getmeas Heart v2 - Get Heart v2 - List Measure v2 - Confirmuser User v2 - Getgoals Stetho v2 - Get Stetho v2 - List Notify - Get Notify - List Notify - Update Notify - Revoke Notify - Subscribe |
| user.info | Access user account information, linked devices, goals, and manage device linking. Also required to list and subscribe to user-related notifications. | User v2 - Get User v2 - Getdevice User v2 - Getgoals User v2 - Link User v2 - Unlink Notify - List Notify - Subscribe |
| user.sleepevents | Scope used to receive notifications when sleep events happen (bed in, bed out, inflate done). | Notify - List Notify - Subscribe |
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.