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
.
access_token
: Expires after 3 hoursrefresh_token
: Expires after 1 year- Old
refresh_token
: Expires 8 hours after new issuance or once the newaccess_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
andrefresh_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 };
}