Glossary

Access Token

This token is unique to each user. It gives access to the API and is linked to your app. It expires after three hours. It can be refreshed using a Refresh Token.

Authentication Token

Once the user allows your app to access their data, this token is generated and set in the redirect URL. It can be used once and is valid for a limited time.

Breathing Disturbance

Recommended ranges for the breathing disturbance intensity:

  • from 0 to 30: low
  • from 30 to 60: medium
  • higher than 60: high
note
  • The user has to enter valid settings in his profile (age, height, weight, gender) to get a correct breathing disturbance intensity value.
  • Breathing disturbance intensity is only calculated for nights longer than five hours

Callback URL

The partner URL is called by our system to send notifications through HTTP POST requests. Make sure that your server can handle a HTTP HEAD request called to verify the validity of your URL.

note

Your URL must:

  • start with https
  • be a valid URL, provided as a URL-encoded string. Please see w3schools URL encoding reference to learn more about URL encoding.
  • not be greater than 255 characters.
  • not contain an IP or 'localhost'. Only ports 80 and 443 are permitted.

Client ID and Client Secret

Required parameters used to authenticate your request during the OAuth 2.0 process. You can get them from your app page.

Heart Rate Zones

Heart rate zones are calculated based on user age and maximum heart rate (hr_max). Knowing their heart rate zones can help users improve their health and fitness and stay in an appropriate heart rate range for their body.

  • Light: Up to 50% of maximum heart rate (hr_max) User heart rate will be in the light zone at rest and during daily activities such as brushing teeth, preparing food, or light walking. A heart rate in this zone does not indicate exercise, and will not promote cardiovascular conditioning.

  • Moderate: 50-70% of maximum heart rate (hr_max) The user's heart rate will hit this zone during most moderate-intensity exercise. At this heart rate, the user's respiration will deepen, as more oxygen is inhaled with each breath, but the intensity should be sustainable. Exercising in this zone is best for improving overall health, basic endurance, and fat burning.

  • Intense: 70-90% of maximum heart rate (hr_max) The user's heart rate will hit this zone during most high-intensity exercise. Once the user's heart rate enters this zone, their respiration rate will increase, and it will be difficult to speak more than a few words at a time. Exercising in this zone is best for improving aerobic fitness, performance and speed.

  • Maximum: 90-100% of maximum heart rate (hr_max) This heart rate range can only be sustained for a few minutes at most. Completing short intervals of exercise in this zone can help athletes improve their speed and aerobic performance. There is no need to hit a heart rate in this zone for general health and fitness, and Withings recommends not exercising in this zone without consulting a doctor.

Refresh Token

This token is unique. It is linked to the user and your app. It is valid for one year. It is used to refresh the Access Token. When you do this, a new Refresh token is sent back to you.

Scope

A scope is a permission that allows your app to access associated services. You have to specify the list of permissions during the OAuth 2.0 - Get your authentication step. The customer must give your app access to associated data. Refer to Withings API list to discover which scope we need to use.

Sleep events

Sleep events are triggered when users get in or out of bed. This feature is only available for Withings Sleep. For more information, see the notifications section.

Environment

The field of your app used to specify when running in a development or production environment. For a production environment, callback URL validation is stricter because a valid URL in HTTPS is required. For the development environment, the number of users is limited to ten.