Authentication

Data privacy

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

Getting your authorization code

Access and refresh tokens are obtained by using an authorization code to call the requesttoken action on Withings OAuth2 API oauth2 webservice. Depending on your integrations, you will obtain your authorization code differently :

  • For partners integrating our App to App solution, an OAuth2.0 flow followed by a permission page is presented to the user. When the user allows the partner to access their data, the partner will get hold of the authorization code.
  • For partners integrating our SDK solution, a user creation request will be performed server side, the server will then get the authization code for that user. More information about this flow can be found on Withings SDK documentation
  • For partners using our cellular devices solutions, user creation is also performed server side when using the creating a user order or activating a user's device. Those requests will return the authorization code for that user. See the Cellular Activation API documentation for more information.

Access and refresh tokens

  • The access_token is always provided with a refresh_token.
  • The refresh_token must only be used to request a new access_token once it has expired.
  • 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.
  • 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.
Token expiration

Anaccess_tokenexpires after 3 hours.

Arefresh_tokenexpires after a year.

When you request newaccess_token and refresh_token, the former refresh_token stops being valid after 8 hours, or as soon as the new access_token is used. This is a safety net in case you were not able to store the new access_token and refresh_token after requesting them.

App to app integration authentication flow

The OAuth 2.0 authentication application flow work as follows:

usage_flow
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.

note

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

SDK integration authentication flow

Please refer to the Withings SDK documentation.

Cellular device integration authentication flow

Please refer to the Cellular Activation API documentation.

Kick-start your integration

You can find tools to help you quickly implement Withings API authentication on this page.

Help

Login required

Please login in order to file a request. If you did not create a developer account yet, you can create one by clicking the Signup button.

OK