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. | Measure v2 - Getactivity Measure v2 - Getintradayactivity Measure v2 - Getworkouts Sleep v2 - Get Sleep v2 - Getsummary |
| user.metrics | Get data related to user ponctual measurements. | Measure - Getmeas Heart - Get Heart - List |
| user.info | Get 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.sleepevents | Scope 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.