openapi: 3.0.3 info: version: '2.0' title: Withings developer documentation answers oauth2 API description: These webservices allows you to get user's answers from surveys servers: - url: https://wbsapi.withings.net/ tags: - name: oauth2 x-displayName: OAuth2 description: "
The Withings API uses OAuth 2.0, an industry-standard protocol for authorization.
OAuth 2.0 enables your application to access user-specific data with a secure and seamless way without requiring users to share their Withings credentials with your app.
\n
\n The Withings API supports the Authorization Code Flow, which is suitable for server-side applications. In this flow, your application will obtain an authorization code from the user, which can then be exchanged for an access token and refresh token.\n

\n There are two ways to obtain the authorization code:
\n
\n 1. **Web Authorization Flow**: Redirect the user to the Withings authorization endpoint, where they can grant permission for your app to access their Withings data.
\n 2. **Account Creation Flow (contract partners only)**: Obtain the authorization code after account creation (Cellular Devices/SDK only) .
\n
\n To use OAuth 2.0 with the Withings API, follow these general steps:
\n
\n 1. **Request user authorization/Create an account**: Use one of the two methods mentioned above to obtain an authorization code from the user.
\n 2. **Obtain an access token**: Exchange the authorization code for an access token and refresh token.
\n 3. **Access the API**: Include the access token in your API requests to access user-specific data from the Withings API.
\n 4. **Refresh tokens**: Use the refresh token to obtain new access tokens when the current ones expire.
\n
\n Please refer to the appropriate [Integration Guide](https://developer.withings.com/developer-guide/v3/withings-solutions/integration-guides) to know which method you should use." paths: https://account.withings.com/oauth2_user/authorize2: get: tags: - oauth2 description: '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```, and ```YOUR_STATE``` with your actual values.

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.' summary: Authorization URL operationId: oauth2-authorize parameters: - name: response_type in: query required: true schema: type: string description: Must take the constant string value ```code```. - name: client_id in: query required: true schema: type: string description: Your ```Client ID```. - name: state in: query required: true schema: type: string description: A value you define. This can be used to make sure that the redirect back to your site or app wasn’t spoofed. - name: scope in: query required: true schema: type: string description: A comma-separated list of permission scopes to request from the user. See the [available scopes](/developer-guide/v3/integration-guide/public-health-data-api/get-access/oauth-authorization-url/#scopes) for the full list and the actions they allow. - name: redirect_uri in: query required: true schema: type: string description: "The URI we should redirect the user to after choosing to authorize or not your app. This URI must be set as ```Callback Url``` in your partner application. It is possible to use multiple URLs by separating them with a comma.
Examples:
\n\t\t\t\t\t\t\t\t\t" - name: mode in: query required: false schema: type: string description: Only set to use the demo user. For demo user must take the constant string value ```demo```. responses: 200: description: ' (Click to unfold)' x-codeSamples: [] https://wbsapi.withings.net/v2/oauth2: post: tags: - oauth2 description: Use this endpoint to request an ```access token``` and ```refresh token``` from an ```authorization code``` or refresh an existing ```access token```.

**Important:** Don't forget to save the userid included in the response in your database.

**Note:** You can use this webservice either by signing the call or using the secret. Toggle the request body schema to see the parameters for the 2 options.

**Note:** Toggle the ```grant_type``` to see the different parameters that must be used depending if you're refreshing a token or using an authorization code.
summary: OAuth 2.0 - Request Access and Refresh Tokens operationId: oauth2-getaccesstoken requestBody: required: true content: Using client secret: schema: type: object discriminator: propertyName: grant_type required: - grant_type - action mapping: authorization_code: '#/components/schemas/TokenRequestWithClientSecret' refresh_token: '#/components/schemas/TokenRequestRefreshWithClientSecret' properties: action: type: string description: Must take the value ```requesttoken```. Using signature: schema: type: object discriminator: propertyName: grant_type required: - grant_type - action mapping: authorization_code: '#/components/schemas/TokenRequestWithSignature' refresh_token: '#/components/schemas/TokenRequestRefreshWithSignature' properties: action: type: string description: Must take the value ```requesttoken```. responses: 200: description: ' (Click to unfold)' content: application/json: schema: type: object properties: status: type: integer description: Response status. See Status section for details. body: type: object description: Response data. properties: userid: type: integer description: The id of the user. example: 363 access_token: type: string description: Your new Access Token. example: a075f8c14fb8df40b08ebc8508533dc332a6910a refresh_token: type: string description: Your Refresh Token. example: f631236f02b991810feb774765b6ae8e6c6839ca expires_in: type: integer description: Access token expiry delay in seconds. example: 10800 scope: type: string description: You can get only the scope that the user accepted with the Token you have. Scopes can be 'user.info' 'user.metrics' 'user.activity' 'user.sleepevents' and must be separated by a coma. example: user.info,user.metrics csrf_token: type: string example: PACnnxwHTaBQOzF7bQqwFUUotIuvtzSM token_type: type: string description: 'HTTP Authorization Header format: Bearer' example: Bearer x-codeSamples: - lang: PHP source: " 'requesttoken',\n\t'grant_type' => 'authorization_code',\n\t'client_id' => '7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67',\n\t'client_secret' => 'd9286311451fc6ed71b372a075c58c5058be158f56a77865e43ab3783255424f',\n\t'code' => 'mtwsikawoqleuroqcluggflrqilrnqbgqvqeuhhh',\n\t'redirect_uri' => 'https://www.withings.com'\n]));\n\n$rsp = curl_exec($ch);\ncurl_close($ch);\n\nvar_dump($rsp);\n\n?>" - lang: CURL source: curl --data "action=requesttoken&grant_type=authorization_code&client_id=7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67&client_secret=d9286311451fc6ed71b372a075c58c5058be158f56a77865e43ab3783255424f&code=mtwsikawoqleuroqcluggflrqilrnqbgqvqeuhhh&redirect_uri=https://www.withings.com" 'https://wbsapi.withings.net/v2/oauth2' ' https://wbsapi.withings.net/v2/oauth2': post: tags: - oauth2 description: '**This service will only work for partners having signed a contract with Withings (Withings Mobile SDK or Withings Cellular).** To generate a new authorization code for standard end-user accounts, your user will have to authorize your application to the Web Authorization Flow again.

This service allows you to retrieve a new authorization code in the event that the refresh token is invalid for a user belonging to your namespace. ' summary: OAuth 2.0 - Retrieve a new authorization code operationId: oauth2-recoverauthorizationcode parameters: - name: action in: query required: true schema: type: string description: Must take the string value ```recoverauthorizationcode```. - name: client_id in: query required: true schema: type: string description: Your ```Client ID```. - name: nonce in: query required: true schema: type: string description: A random token used to prevent replay attacks (Cf. [Signature v2 - Getnonce](#operation/signaturev2-getnonce)). - name: signature in: query required: true schema: type: string description: Hash of params (Cf. [Signature hash protocol](/developer-guide/v3/get-access/sign-your-requests)). - name: userid in: query required: true schema: type: integer description: User's identifier responses: 200: description: ' (Click to unfold)' content: application/json: schema: type: object properties: status: type: integer description: Response status. See Status section for details. body: type: object description: Response data. properties: user: type: object properties: code: type: string description: Authorization Code that must be used to retrieve access_token and refresh_token. (Read the "Get access to your user's data" section of your [integration guide](/developer-guide/v3/withings-solutions/integration-guides) to learn more about how to get this parameter.) example: 490ed603fe9bd2ce10027bdba0c932069cd27085 x-codeSamples: - lang: PHP source: " 'recoverauthorizationcode',\n\t'client_id' => '7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67',\n\t'signature' => '58c0c4ad271fb20df9b96c63dc68d6c550c0b7896f743262fc4c5b9261f32ab2',\n\t'nonce' => 'c455541b8f9111689adb647d32fac07a6ffe462d',\n\t'userid' => 489418\n]));\n\n$rsp = curl_exec($ch);\ncurl_close($ch);\n\nvar_dump($rsp);\n\n?>" - lang: CURL source: curl --data "action=recoverauthorizationcode&client_id=7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67&signature=58c0c4ad271fb20df9b96c63dc68d6c550c0b7896f743262fc4c5b9261f32ab2&nonce=c455541b8f9111689adb647d32fac07a6ffe462d&userid=489418" 'https://wbsapi.withings.net/v2/oauth2' ' https://wbsapi.withings.net/v2/oauth2': post: tags: - oauth2 description: 'This service allows you to get a list of all users that have authorized your application to fetch their data. **This service is limited to partners who are integrating with Withings Pro solutions. This service will only work for partners having signed a contract with Withings.**' summary: OAuth 2.0 - Get user list operationId: oauth2-listusers parameters: - name: action in: query required: true schema: type: string description: Must take the string value ```listusers```. - name: client_id in: query required: true schema: type: string description: Your ```Client ID```. - name: nonce in: query required: true schema: type: string description: A random token used to prevent replay attacks (Cf. [Signature v2 - Getnonce](#operation/signaturev2-getnonce)). - name: signature in: query required: true schema: type: string description: Hash of params (Cf. [Signature hash protocol](/developer-guide/v3/get-access/sign-your-requests)). - name: offset in: query required: false schema: type: integer description: When a first call returns ```more:true``` and ```offset:XX```, set value ```XX``` in this parameter to retrieve next available rows. responses: 200: description: ' (Click to unfold)' content: application/json: schema: type: object properties: status: type: integer description: Response status. See Status section for details. body: type: object description: Response data. properties: hash_userid: type: string example: b1e4ea9c8bf584c8210ff308b19d656e15e9a074cd69178f833f687b95d8a2b5 userid: type: integer description: The id of the user. example: 2685485 email: type: string description: User's email address example: example@mailprovider.com fully_owned: type: boolean description: Whether or not this user has been created by your oauth2 application. Having created the account gives your application additional rights on this account, such as automatically granted authorizations and access to the retrieve tokens webservice. more: type: boolean description: To know if there is more data to fetch or not. offset: type: integer description: Offset to use to retrieve the next data. x-codeSamples: - lang: PHP source: " 'listusers',\n\t'client_id' => '7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67',\n\t'signature' => '58c0c4ad271fb20df9b96c63dc68d6c550c0b7896f743262fc4c5b9261f32ab2',\n\t'nonce' => 'c455541b8f9111689adb647d32fac07a6ffe462d',\n\t'offset' => 0\n]));\n\n$rsp = curl_exec($ch);\ncurl_close($ch);\n\nvar_dump($rsp);\n\n?>" - lang: CURL source: curl --data "action=listusers&client_id=7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67&signature=58c0c4ad271fb20df9b96c63dc68d6c550c0b7896f743262fc4c5b9261f32ab2&nonce=c455541b8f9111689adb647d32fac07a6ffe462d&offset=0" 'https://wbsapi.withings.net/v2/oauth2' ' https://wbsapi.withings.net/v2/oauth2': post: tags: - oauth2 description: This service allows to revoke the access your application have been granted to a user's data. After calling this webservice, your access and refresh tokens for this user will become invalid, and the data update notifications for this user will be automatically unsubscribed. summary: OAuth 2.0 - Revoke user access operationId: oauth2-revoke parameters: - name: action in: query required: true schema: type: string description: Must take the string value ```revoke```. - name: client_id in: query required: true schema: type: string description: Your ```Client ID```. - name: nonce in: query required: true schema: type: string description: A random token used to prevent replay attacks (Cf. [Signature v2 - Getnonce](#operation/signaturev2-getnonce)). - name: signature in: query required: true schema: type: string description: Hash of params (Cf. [Signature hash protocol](/developer-guide/v3/get-access/sign-your-requests)). - name: userid in: query required: true schema: type: integer description: User's identifier. responses: 200: description: ' (Click to unfold)' content: application/json: schema: type: object properties: status: type: integer description: Response status. See Status section for details. body: type: object description: Response data. properties: [] x-codeSamples: - lang: PHP source: " 'revoke',\n\t'client_id' => '7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67',\n\t'signature' => '58c0c4ad271fb20df9b96c63dc68d6c550c0b7896f743262fc4c5b9261f32ab2',\n\t'nonce' => 'c455541b8f9111689adb647d32fac07a6ffe462d',\n\t'userid' => 489418\n]));\n\n$rsp = curl_exec($ch);\ncurl_close($ch);\n\nvar_dump($rsp);\n\n?>" - lang: CURL source: curl --data "action=revoke&client_id=7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67&signature=58c0c4ad271fb20df9b96c63dc68d6c550c0b7896f743262fc4c5b9261f32ab2&nonce=c455541b8f9111689adb647d32fac07a6ffe462d&userid=489418" 'https://wbsapi.withings.net/v2/oauth2' ' https://wbsapi.withings.net/v2/oauth2': post: tags: - oauth2 description: This webservice gives your clientID access to a demo account containing dummy data summary: OAuth 2.0 - Get access to demo account operationId: oauth2-getdemoaccess parameters: - name: action in: query required: true schema: type: string description: Must take the string value ```getdemoaccess```. - name: client_id in: query required: true schema: type: string description: Your ```Client ID```. - name: nonce in: query required: true schema: type: string description: A random token used to prevent replay attacks (Cf. [Signature v2 - Getnonce](#operation/signaturev2-getnonce)). - name: signature in: query required: true schema: type: string description: Hash of params (Cf. [Signature hash protocol](/developer-guide/v3/get-access/sign-your-requests)). - name: scope_oauth2 in: query required: true schema: type: string description: A comma-separated list of permission scopes to request from the user. See the [available scopes](/developer-guide/v3/integration-guide/public-health-data-api/get-access/oauth-authorization-url/#scopes) for the full list and the actions they allow. responses: 200: description: ' (Click to unfold)' content: application/json: schema: type: object properties: status: type: integer description: Response status. See Status section for details. body: type: object description: Response data. properties: access_token: type: string description: Your new Access Token. example: a075f8c14fb8df40b08ebc8508533dc332a6910a refresh_token: type: string description: Your Refresh Token. example: f631236f02b991810feb774765b6ae8e6c6839ca expires_in: type: integer description: Access token expiry delay in seconds. example: 10800 x-codeSamples: - lang: PHP source: " 'getdemoaccess',\n\t'client_id' => '7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67',\n\t'signature' => '58c0c4ad271fb20df9b96c63dc68d6c550c0b7896f743262fc4c5b9261f32ab2',\n\t'nonce' => 'c455541b8f9111689adb647d32fac07a6ffe462d',\n\t'scope_oauth2' => 'user.activity,user.metrics'\n]));\n\n$rsp = curl_exec($ch);\ncurl_close($ch);\n\nvar_dump($rsp);\n\n?>" - lang: CURL source: curl --data "action=getdemoaccess&client_id=7573fd4a4c421ddd102dac406dc6e0e0e22f683c4a5e81ff0a5caf8b65abed67&signature=58c0c4ad271fb20df9b96c63dc68d6c550c0b7896f743262fc4c5b9261f32ab2&nonce=c455541b8f9111689adb647d32fac07a6ffe462d&scope_oauth2=user.activity,user.metrics" 'https://wbsapi.withings.net/v2/oauth2' ' https://wbsapi.withings.net/v2/oauth2': post: tags: - oauth2 description: 'This service allows creation of a new OAuth 2.0 application. **This service is part of Withings Pro Solutions. You won''t be able to use it if you did not sign a contract with Withings. Uncontracted partners should use the developer dashboard to create their applications.**' summary: OAuth 2.0 - Create OAuth2.0 application operationId: oauth2-createclient parameters: - name: action in: query required: true schema: type: string description: Must take the string value ```createclient```. - name: client_id in: query required: true schema: type: string description: Your ```Client ID```. - name: nonce in: query required: true schema: type: string description: A random token used to prevent replay attacks (Cf. [Signature v2 - Getnonce](#operation/signaturev2-getnonce)). - name: signature in: query required: true schema: type: string description: Hash of params (Cf. [Signature hash protocol](/developer-guide/v3/get-access/sign-your-requests)). - name: name in: query required: true schema: type: string description: Specifies the OAuth2.0 application's name - name: description in: query required: true schema: type: string description: Brief summary of the application - name: intended_environment in: query required: true schema: type: string description: 'Indicates intended operation environment. Allowed values are: ```dev```, ```stage``` and ```prod```' - name: intended_integrations in: query required: true schema: type: array of strings description: 'Specifies Withings Solutions to be used. Allowed values are: ```app_to_app```, ```sdk```, ```cellular``` and ```logistics```' - name: redirect_uris in: query required: true schema: type: array of strings description: List of redirect uris responses: 200: description: ' (Click to unfold)' content: application/json: schema: type: object properties: status: type: integer description: Response status. See Status section for details. body: type: object description: Response data. properties: client_id: type: string example: 1130b57432f560c3a686803901e56954f46082c9825a0a598a1a827c56177ca5 client_secret: type: string example: 40eac75e29c642223793bbdd1faa85e9772638b542c016738b8106d64cc6c1ea name: type: string example: App Name desc: type: string example: App Description img: type: string example: \/uploads\/image.png is_restricted: type: boolean organization_id: type: integer example: 12345 x-codeSamples: - lang: PHP source: " 'createclient',\n\t'organization_id' => 12345,\n\t'name' => 'My OAuth2.0 Application',\n\t'description' => 'An OAuth2.0 Application',\n\t'redirect_uris' => '[\"https:\\\\/\\\\/www.withings.com\",\"https:\\\\/\\\\/www.test.com\"]',\n\t'intended_integrations' => '[\"app_to_app\"]',\n\t'intended_environment' => 'dev'\n]));\n\n$rsp = curl_exec($ch);\ncurl_close($ch);\n\nvar_dump($rsp);\n\n?>" - lang: CURL source: curl --data "action=createclient&organization_id=12345&name=My OAuth2.0 Application&description=An OAuth2.0 Application&redirect_uris=["https:\\/\\/www.withings.com","https:\\/\\/www.test.com"]&intended_integrations=["app_to_app"]&intended_environment=dev" 'https://wbsapi.withings.net/v2/oauth2' x-tagGroups: - name: Api Reference Content tags: - oauth2 - dropshipment - order - user - measure - heart - stetho - sleep - notify - survey - answers - signature - rawdata - device - models - response_status - Glossary - nudge - nudgecampaign