Fwd: October 2015 Fitbit Web API Breaking Changes
Bastian Greshake
OAuth 2.0 is HereWe are excited to announce that OAuth 2.0 now is the recommended authorization protocol for the Fitbit Web API. Thank you for your help testing during the beta period.
Documentation for using OAuth 2.0 with the Fitbit Web API is available at https://dev.fitbit.com/docs/oauth2 .
Changes since the OAuth 2.0 Beta
If you participated in the OAuth 2.0 public beta, here are the most recent changes:
All desired scope values must now be specified. Previously, OAuth 1.0a-equivalent scope values were added to all authorization requests.
HTTP status codes and response bodies for errors now conform to the OAuth 2.0 framework with one exception. Though the OAuth 2.0 framework specifies that people should be redirected to your application with an error code when your application provides invalid authorization page URL parameters, following this portion of the framework could assist in a phishing attack. Because of this, we’ve chosen intentionally to not conform. The Fitbit Web API will only redirect a person from the authorization page when the person grants or denies access to your application.
OAuth 1.0a Removal
Applications should upgrade to OAuth 2.0 by March 14, 2016. OAuth 1.0a support will be removed from the Fitbit Web API six months from now on April 12, 2016.
A one hour blackout test will be performed on March 14, 2016. During the test, all OAuth 1.0a requests will fail. You should upgrade your application to OAuth 2.0 by March 14th and use the blackout test as an opportunity to verify no part of your application still uses OAuth 1.0a.
Upgrading from OAuth 1.0a
Upgrading Access Tokens
Fitbit has created a custom method for applications to exchange OAuth 1.0a access tokens and access token secrets for OAuth 2.0 access and refresh tokens. This feature allows your application to upgrade to OAuth 2.0 without our users needing to re-authorize your application. This process is described in the documentation.
Token Expiry Considerations
OAuth 1.0a access tokens never expire. However, OAuth 2.0 access tokens regularly expire. Consider how this may affect your technical integration and user experience.
If your application has a server component, an OAuth 2.0 access token can be refreshed without end user interaction using the refresh token provided at authorization. The Fitbit API will return new access and refresh tokens each time. The refresh token may only be used once, so it’s critical that your application properly store the new access and refresh tokens when it receives them. If your application has multiple processes operating concurrently, your application will need to account for token expiration and only attempt to refresh the token once when it expires. If your application fails to store the refreshed tokens, the user will need to re-authorize your application to obtain new tokens.
If your application is client-side only (such as a downloadable or Web browser app), it can request a long-lived access token up to 30 days. At the end of 30 days, your application must then prompt the user for continued permission.
XML Inaccessible via OAuth 2.0
Fitbit deprecated XML support a year ago. Applications will not be able to request the XML format when using OAuth 2.0. (The specialized XML format TCX remains supported in OAuth 2.0.)
OAuth 1.0a applications requesting XML will need update to use JSON. We recommend switching to JSON resources before upgrading your application to OAuth 2.0.
We’re Here to Help
While OAuth 2.0 is an industry defined standard that is quite a page turner, we’ve tried to explain OAuth 2.0 accessibly and succinctly in our own documentation. If you have questions, a team of Fitbit engineers is ready to help you in the Web API Support Forum.
OAuth 2.0 is a significant improvement from OAuth 1.0a. It gives people more control of their data and provides a new security model for distributed applications. We’e excited to make OAuth 2.0 available and hope you enjoy this feature.
—The Fitbit Web API Team
