Application Design
chevron down
 

Application Design

Data Types

Access Modes

Applications operate in a read-only or read and write manner. This is an application-level setting and applies to all scopes. This can be configured in application settings on dev.fitbit.com.

WARNING: Changing the read-only/read and write settings will immediately invalidate all existing access tokens.

Dates

All dates are displayed in the format YYYY-MM-DD. The Nutrition API supports the ISO-8601 standard for date values with the following conditions:

  • a 4-digit year [YYYY]
  • year values within the range of 0000-9999
  • no enforcement of start date restrictions implied by the ISO-8601 standard or other epoch

Numerical Ids

All integer ids for resources should be considered unsigned 64 bit integers.

Time Zones

Fitbit does not support time zones for data. Users can specify a time zone in their settings, but this offset is only used to determine the start of their 24-hour period. As such, there is no way to request a specific time zone, because all data is aligned with the user's specified UTC offset. All date and time related fields in the API requests and responses are rendered in the local time of the resource owner's timezone (either the authorized user or the owner of the resource requested).

A user's current time zone and UTC offset in milliseconds can be retrieved through the Get Profile endpoint.

Some endpoints such as activity and heart rate support the query parameter “timezone=UTC” for returning the data at UTC instead of the user’s timezone settings. Please see the specific endpoints to know if it supports the “timezone” query parameter.

Headers

Executing the Web API endpoints requires using the appropriate headers and token. See API Endpoint Guide for details.

Intraday Data

The Web APIs have the ability to expose a finer granularity of data collected throughout the day. This collection of data is called Intraday data. Intraday data is available through the Activities and Heart Rate time series endpoints. Intraday support can extend the detail-level response to include 1min or 15min for Activity, and 1sec or 1min for Heart Rate. A Fitbit developer’s personal Intraday data is automatically available through the “Personal” application type.

3rd-party developers who want access to retrieve other Fitbit users’ Intraday data through the “Client” or “Server” application types are granted on a case-by-case basis. Applications must demonstrate the necessity to create a great user experience. Fitbit is very supportive of non-profit research and personal projects. Commercial applications require thorough review and are subject to additional requirements. Only select applications are granted access and Fitbit reserves the right to limit this access. 3rd-party developers who require intraday access should submit a request by filling out the
Intraday Request form.

Localization

Language

Some of the API responses include text fields that may be suitable for displaying to the end user. If available, setting the Accept-Locale header will return a translated response. Fitbit currently supports the following locales:

Accept-Locale Locale
en_AU Australia
fr_FR France
de_DE Germany
ja_JP Japan
en_NZ New Zealand
es_ES Spain
en_GB United Kingdom
en_US United States (default)

Unit Systems

API calls reveal data and log resource values in one of the unit systems based on the value of the Accept-Language header. If an endpoint respects the Accept-Language header, it is explicitly mentioned in the endpoint details.
The Accept-Language header value is case sensitive. Improper case or misspelling will result in the metric unit system.

Accept-Language Unit System
en_US United States
en_GB United Kingdom
none of the above or not provided Metric

Units

United States

Unit Type Units
duration milliseconds
distance miles
elevation feet
height inches
weight pounds
body measurements inches
liquids fluid ounces (fl oz)
blood glucose milligrams per deciliter (mg/dL) (mass concentration)

United Kingdom

Unit Type Units
duration milliseconds
distance kilometers
elevation meters
height centimeters
weight stone*
body measurements centimeters
liquids millimeters
blood glucose millimoles per liter (mmol/l) (molar concentration)
NOTE: the API uses decimal values for all unit types, so UK weight will be expressed as 10.5 stone instead of 10 stone 7 pounds.

Metric

Unit Type Units
duration milliseconds
distance kilometers
elevation meters
height centimeters
weight kilograms
body measurements centimeters
liquids millimeters
blood glucose millimoles per liter (mmol/l) (molar concentration)

Localizing Nutritional Data

Requests to the Nutrition APIs may specify the foodDatabase query parameter with the desired food locale. See the Get Food Locales API for supported values.

Privacy Controls

Some APIs allow fetching resources of other users with full OAuth authorization on behalf of the authorized user or public data without full OAuth authorization on behalf of the client. The following user profile privacy controls affect the visibility of this data: About Me, Age and Height, Location (affect profile fields visibility), Weight & BMI, Activities, Foods, Friends, Sleep (affect complete access to those endpoints). An authorized user always has access to all of their own data and is not affected by privacy controls.

Rate Limits

An application’s rate limit is 150 API requests per hour for each user who has consented to share their data; and it resets at the top of each hour. The usage count is incremented for all API requests that use access tokens. Since the API requests are metered per user, your application will not be constrained as your user base grows.

Hitting the Rate Limit

The application will receive an HTTP 429 response from the Fitbit API when a request is not fulfilled due to reaching the rate limit. A response header is sent with the number of seconds until the rate limit is reset before making API calls again. The rate limit is reset at the top of the hour.

Response Headers

The Fitbit Web API responses include headers that provide the application’s rate limit status. The response headers are

  • Fitbit-Rate-Limit-Limit: The quota number of calls.
  • Fitbit-Rate-Limit-Remaining: The number of calls remaining before hitting the rate limit.
  • Fitbit-Rate-Limit-Reset: The number of seconds until the rate limit resets.

The data in the rate limit headers is updated asynchronously and approximate. A slight delay when decrementing the remaining count could be expected for larger implementations. This would result with the application receiving a 429 Too Many Requests status code sooner than anticipated, if the application does not track its usage.

Automatic Email Notices

The Fitbit Web API will email the application owner when the hourly rate limit has exceeded. These are courtesy notices. Action is not required unless there is interest to optimize the Fitbit integration.

Redirect URL

This URL is the location in your application the Fitbit user is sent after user consent has occurred.

During the authorization process, the user is sent to Fitbit’s OAuth 2.0 Authorization web page. The user is returned back to your application after successful authorization via the redirect URL. Native applications can use custom URL schemes as redirect URLs to redirect the user from the browser back to the application requesting permission.

According to RFC 3986, Section 4.3, the redirect URL is absolute and should not be fragmented. The syntax for the redirect URL should be

absolute-URI = scheme ":" hier-part [ "?" query ]

You must specify the full redirect URL in your application settings on https://dev.fitbit.com. An application may have multiple redirect URLs registered by putting one redirect URL per line in your application settings. Fitbit strongly recommends that you always specify the intended redirect URL value with the redirect_uri parameter when sending users to the authorization page. The redirect_uri must be an exact match to one of the values specified in your application settings.

Note: Use the state parameter if you need variability in your redirect URI.

Unicode characters are allowed, but should be converted to punycode. Not doing so will result in a URL mismatch during the OAuth flow.

When using the Authorization Code Grant Flow or the Authorization Code Grant Flow with PKCE, Fitbit will append #_=_ at the end of your redirect URL upon success or failure of the authorization.

Note: Fitbit only supports HTTPS for redirect URLs.

Social Login Support

The Fitbit Web API supports social login (Google only) only for the Authorization Grant Flows as part of the web single sign-on (SSO). When the OAuth 2.0 authorization flow requires access to the Fitbit user’s account while prompting for user consent, social login can be used with the Fitbit web application. If the user has already logged into their www.fitbit.com account using their Google account, they won’t be shown the sign-in form prior to the authorization consent form, unless prompt=login.

Scopes

All Fitbit API endpoints that retrieve user data require user consent to that data collection through one or more scopes. The application must provide the list of scopes when calling the Authorize endpoint. The access token issued will only contain the scopes the Fitbit user authorized.

Available Scopes

activity Includes activity data and exercise log related features, such as steps, distance, calories burned, and active minutes
heartrate Includes the continuous heart rate data and related analysis
location Includes the GPS and other location data
nutrition includes calorie consumption and nutrition related features, such as food/water logging, goals, and plans
profile includes basic user information
settings includes user account and device settings, such as alarms
sleep includes sleep logs and related sleep analysis
social includes friend-related features, such as friend list, invitations, and leaderboard
weight includes weight and body fat information, such as body mass index, body fat percentage, and goals

When the application begins the authorization process, the OAuth 2.0 Authorization page will be displayed to the Fitbit user requesting permission to access the data sets that are required by the application. OAuth 2.0 refers to these permissions as “scopes”. Applications should only request permission for scopes they intend to access or modify.

NOTE: The application is not allowed to enable all scopes by default or force a user to enable all scopes. Instead, we suggest encouraging the users to enable all scopes by stating something like “For the best user experience, we recommend you enable all listed scopes” See Fitbit’s Platform Terms of Service for more details. It is ultimately up to the Fitbit user whether or not all of the scopes are enabled. Therefore, the application should not break if a scope is not granted.

Displaying the Authorization Page

If an access token is not automatically available to Fitbit, the Fitbit OAuth 2.0 Authorization page is presented to the user in a web form during the authorization process. For security consideration, the consent page must be presented in a dedicated browser view. Fitbit users can only confirm they are authenticating with the genuine Fitbit.com site if they have the tools provided by the browser, such as the URL bar and Transport Layer Security (TLS) certificate information.

  • Native applications - the authorization page must open in the default browser. Native applications can use custom URL schemes as redirect URIs to redirect the user back from the browser to the application requesting permission.
  • iOS applications - may use the SFSafariViewController class instead of app switching to Safari. Use of the WKWebView or UIWebView class is prohibited.
  • Android applications - may use Chrome custom tabs instead of application switching to the default browser. Use of WebView is prohibited.
  • Web applications - do not use an iframe. Web applications may use a pop-up window, so long as the URL bar is visible.
WARNING - DO NOT embed the Authorization Page. Any attempt to embed the OAuth 2.0 authentication page will result in your application being banned from the Fitbit API.

Example 
screenshot of the Fitbit OAuth 2.0 consent page

Tokens

A token is an object that provides access to a specific resource. The Fitbit Web APIs utilize 3 different types of tokens.

  • The Basic Token is the Base64 encoded string of the application's client id and secret concatenated with a colon (e.g. [client_id]:[client_secret]). The basic token is used with access token and refresh token requests.
  • The Access Token, also known as the Bearer Token, is a unique, signed JWT object used to denote the permissions a Fitbit user has granted to a specific application. Access tokens are generated for all authorization flows and are used when executing an API call. These tokens can be used multiple times, but they do have an expiration date.
  • The Refresh Token is used to obtain a new access token and a new refresh token when the existing access token has expired. This is supported only with the Authorization Code Grant flow. Refresh tokens are unique to its associated access token. They can only be used once, but do not expire.
Note: Fitbit API access tokens use the JSON Web Token (JWT) format. Fitbit reserves the right to change the contents and format of these tokens at any time. Client applications should not create dependencies upon the token format. Access tokens and refresh tokens may be up to 1,024 bytes in size.

Access Token Usage

An access token intentionally is short lived. This is an important security mechanism of OAuth 2.0. When using the Authorization Code Grant Flow, the access tokens have an eight-hour lifetime by default. To make a request to the Fitbit API using OAuth 2.0, simply add an Authorization header to the HTTPS request with the user's access token.

Example

GET https://api.fitbit.com/1/user/-/profile.json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleH...

When an access token expires, an HTTP 401 error will be returned. Your application will need to use the refresh token to obtain a new access token and refresh token pair. See Refresh Token.

Web Browser Compatibility

The Fitbit API and its implementation of OAuth 2.0 are designed to work with the current and one previous version of Apple Safari, Google Chrome, Microsoft Edge, and Mozilla Firefox. When a new version of a web browser is released, Fitbit begins supporting the new version and discontinues support for the third most recent version.