Application Design

Application Types

Fitbit uses the term "application type" to describe the application's architecture and whose data can be accessed. The 3 application types are:

• "Server" (recommended) applications are usually multi-tier and have a server component to the architecture. They provide server-side authentication where the application and server communicate via a web service. The application has the ability to access a user's intraday data by completing the Intraday Request form.
• "Client" applications are usually single-tier and do not have a server component to the architecture. These applications allow for client-side authentication. The application has the ability to access a user's intraday data by completing the Intraday Request form.
• "Personal" applications can have either the client or server architecture. The application can only access the data in the developer's Fitbit account, including their intraday data. Completing the Intraday Request form is not needed.

The application type is recorded within the registered application settings, and it can be changed as needed. For example, a person might set the application type to "personal" during the development cycle or for a personal project. This gives the developer access to query their data using all of the Fitbit public and intraday endpoints. When ready to test against other Fitbit user's data or deploy the application to production, it would make sense to change the application type to either "client" or "server".

To determine the recommended OAuth 2.0 authorization flow that should be used for your application type, see Authorization.

Data Availability

Updates to the user's data is only available after they sync their activity tracker or manually enters new data into the Fitbit mobile or web application. The Fitbit device and Fitbit mobile application can automatically sync every 15 minutes when the two are within bluetooth range, the Fitbit application is running on the mobile device, and the mobile device has an active data connection. If the user is tracking activity using MobileTrack, MobileTrack syncs every 30 minutes.

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.

Supported Devices

All Fitbit devices and Google Pixel watches, current and previous, will collect data that is returned through the Web API. The type of data available will depend on the functionality the devices support. The list of current devices can be found on our web site. See Fitbit Products.

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 made available for the Activities, Breathing Rate, Heart Rate, HRV and SpO2 data sets by extending the daily detail-level response. 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:

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.

Units

United States

United Kingdom

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

Localizing the consent page

The Fitbit consent page supports localization. Since it is just a web form, the text is translated based on the user's "Language by Region/Country" setting in their Fitbit account. The user's device or browser language settings may translate the consent language, as well. We do not support a query parameter that forces language conversion.

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, approximately, 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, approximately, 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 is 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

Obtaining Consent through Scopes

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.

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 tokens

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.

Revoked tokens

Users have granular control over read/write access to their data through the Fitbit Web API. When a user revokes consent to your application, their access token becomes invalid and your access to that user's data through the Web API is no longer available. What you do with the data that has already been collected should be clearly documented in your Terms of Service and Privacy Policy. Any guidelines or requirements defined by Fitbit will be specified in our Platform Terms of Service.

Universal Links / App Links

Developers who would like to redirect users from their application to the Fitbit mobile application can do so using either Universal Links on iOS or App Links on Android. This is similar to mobile deep links but is more secure and recommended by Apple and Google. Below is a list of the available URLs that you can use in your application.

There are some things to keep in mind when using our Universal Links / App Links solution.

1. The same URL can be used with Universal Links on iOS or App Links on Android.
2. Your application does not need language-specific links. The application will localize itself using the mobile device’s language.
3. If the Fitbit application is not installed on the device, the link will automatically fail or be directed to a help article, as described above.
4. The URLs will not open properly when typed directly into the desktop or mobile browser. The best way to test the Universal Links / App Links is send yourself an email with the URL included in the body of the message, then open the email on the mobile device and tap the link.

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.

Authorization

Using Subscriptions