Skip to main content

Access and refresh tokens

Now that we've obtained an authorization code, you’ll use that code to request both an access_token and a refresh_token.

The access_token is required to access all Health Data API services, it allows Withings to verify your authorization to access a member’s data. The refresh_token allows you to renew your access_token.

Token Expiration Guideline
  • access_token: Expires after 3 hours
  • refresh_token: Expires after 1 year
  • Old refresh_token: Expires 8 hours after new issuance or once the new access_token is used

Access Token Usage

It must be passed as a Bearer token in the Authorization header.

Example: Authorization: Bearer 05544b41da038f65e3f2d1dd15560b61d1ef3fbf

Refresh Token Usage

The refresh_token is provided along with the access_token.
It has a longer expiration time (1 year) and is used solely to request new access_tokens after they expire.
However, each time you request a new access_token, you also receive a new refresh_token.

Important: Always replace the previous refresh_token with the new one.
Failure to do so may result in losing access once the old refresh_token expires.

To request a new access_token using the refresh_token, call the requesttoken webservice.

Recovering Access

In case you lose access to a valid refresh_token (e.g., if you accidentally fail to replace an expired one), you can still regain access to a user’s data. To do this, you need to generate a new authorization code using the recoverauthorizationcode webservice.

By using this new authorization code, you can then call the getaccesstoken webservice again to receive a valid access_token and refresh_token.

Run In Postman

Important Considerations

While the recovery process allows you to regain access, it should be used sparingly. Needing to recover access frequently indicates potential flaws in your integration. Common issues include:

  • Not properly replacing the refresh_token with the newly issued one.
  • Failing to correctly store the access_token and refresh_token in your database.

Snippets

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 const axios = require('axios'); const { sign, getNonce } = require('./getnonce'); //see signature snippets // Constants const API_ENDPOINT = 'https://wbsapi.withings.net'; const OAUTH2_GRANT_TYPE_AUTHORIZATION_CODE = 'authorization_code'; const REDIRECT_URI = 'localhost:3000'; const CLIENT_ID = 'yourclientid'; const CLIENT_SECRET = 'yourclientsecret'; async function requestTokenAuthorizationCode(nonce, authorization_code) { const params = { action: 'requesttoken', client_id: CLIENT_ID, redirect_uri: REDIRECT_URI, code: authorization_code, grant_type: OAUTH2_GRANT_TYPE_AUTHORIZATION_CODE, nonce: nonce }; params.signature = sign(params, CLIENT_SECRET); const { data } = await axios.post(API_ENDPOINT + 'v2/oauth2', params); const { userid, access_token, refresh_token, scope, expires_in, csrf_token, token_type } = data.body; return { userid, access_token, refresh_token, scope, expires_in, csrf_token, token_type }; }
Help

Login required

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

OK