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.
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
All integer ids for resources should be considered unsigned 64 bit integers.
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.
Executing the Web API endpoints requires using the appropriate headers and token. See API Endpoint Guide for details.
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.
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:
|en_US||United States (default)|
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.
|none of the above or not provided||Metric|
|blood glucose||milligrams per deciliter (mg/dL) (mass concentration)|
|liquids||fluid ounces (fl oz)|
|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.
|blood glucose||millimoles per liter (mmol/l) (molar concentration)|
Localizing Nutritional Data
Requests to the Nutrition APIs may specify the
parameter with the desired food locale. See the
Get Food Locales API for supported values.
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.
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.
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.
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.
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.
|activity||Includes activity data and exercise log related features, such as steps, distance, calories burned, and active minutes.|
|cardio_fitness||Includes the maximum or optimum rate at which the user’s heart, lungs, and muscles can effectively use oxygen during exercise.|
|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.|
|oxygen_saturation||Includes measurements of blood oxygen level.|
|profile||Includes basic user information.|
|respiratory_rate||Includes measurements of average breaths per minute at night.|
|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 and leaderboard.|
|temperature||Includes skin and core temperature data.|
|weight||Includes weight and body fat information, such as body mass index, body fat percentage, and goals.|
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.
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.
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.