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

Identify the User with the userid

The requesttoken response includes a userid. Save it in your database, with the tokens.

  • The userid is the unique identifier of a Withings user. It never changes.
  • Use the userid to link the Withings user to the user in your system. One userid matches one user on your side, and one user on your side matches one userid.
  • Do not use the email address to identify a user. Several Withings users can have the same email address, for example one created in the Withings app and one created by your application.
  • Notifications also include the userid. Use it to find which user the new data belongs to.

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.

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