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.

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

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 };
}