Skip to end of metadata
Go to start of metadata


The Fitbit API uses OAuth Authentication as described in The OAuth 1.0 Protocol. OAuth is an open protocol for clients of the Fitbit API to access Fitbit content on behalf of a Fitbit user.

Recommended Steps

  1. Study the OAuth Flow Diagram.
  2. Study the API client and app reference implementation.
  3. Use the documentation here to implement authentication in your API client and application.

Notes

  • For the following, the API base URL is https://api.fitbit.com
    (currently we are not enforcing the SSL, though it could change in future, production application should always use SSL for the OAuth handshake).
  • We are using Authorization header to pass OAuth parameters. We use HMAC-SHA1 function to generate signature.
  • See the OAuth Flow Diagram for details on the overall flow.
  • The letters after a call description such as  A  and  B  refer to the OAuth Flow Diagram steps.
  • Assuming that the developer will return to browse them more often, call specifics have been placed ahead of other content, such as the OAuth Flow Diagram.

The client requests and receives temporary credentials from Fitbit.

(OAuth Flow Diagram A and B)

Request

POST /oauth/request_token

Authorization header parameters required in alphabetical order:

oauth_callback

Callback URL. The server stores this URL and redirects to it later when user authorizes client.

oauth_consumer_key

The client key agreed upon at registration.

oauth_nonce

Random string uniquely generated by client to allow the server to verify uniqueness of request.

oauth_signature

Signature calculated as described in The OAuth 1.0 Protocol Section 3.4: Signature.

oauth_signature_method

Signature method: HMAC-SHA1, RSA-SHA1, PLAINTEXT, etc.

oauth_timestamp

Timestamp

oauth_version

1.0

Response

status code:

200 OK

header:

Content-Type: application/x-www-form-urlencoded

body:

oauth_token=<temporary-token>&oauth_token_secret=<temporary-token-secret>&oauth_callback_confirmed=true

Example:

Request
Signature Base String
Response
Body

The client redirects the user to Fitbit in order for the user to authorize the client application.

(OAuth Flow Diagram C)

Summary

We have implemented two slightly different workflow for an obtaining user's authorization in terms of workflow and interaction. The first one is a general OAuth 1.0a recommended workflow, and the second one is our custom-tailored simplification to allow smoother user experience for those apps that are implementing the "Sign in with Fitbit" like workflow.

Basic workflow

If an user is already logged to the Fitbit.com we redirect him to a dialog box that provides a basic information about an client that requested a given request code and gives the user an ability to either grant or deny a permission to a requested resource. If an user isn't logged in then we request the user's credentials.

Request 

Notes: 

  1. Generally the UI language of the OAuth authorization page would be defined either from geolocation of the user (for a new user) or by his selected Fitbit.com website locale preference (e.g. "US" (en_US), "Germany" (de_DE) etc.). The default locale would be set to en_US. That said, optional GET parameter locale could be passed in the redirect to override those selections with specific UI locale
  2. We also have a second version of the OAuth UI tailored for mobile browsers. The display parameter is optional and allows to explicitly select mobile version of the page for the user. When omitted it indicates that we SHOULD display dialog optimized for desktop browsers and when specified the dialog optimized for mobile browsers.
  3. You could always force the page to provide the login form instead of just showing "Allow" and "Deny" buttons for the users who already logged in to www.fitbit.com. This should help to avoid situations, where user should log out first in case of environments with more than one Fitbit.com account. This is controlled by adding requestCredentials GET parameter.

REDIRECT to https://www.fitbit.com/oauth/authorize?oauth_token=<temporary-token>[&locale=<locale>][&display=touch][&requestCredentials=true]

Example

Extended workflow

The only difference with the basic workflow is that when an user has already granted access to his data for a given client, we don't ask the user to approve given request and automatically redirect him back to the client (or to PIN page for PIN-based workflows). All request parameters from Basic workflow still available in this case.

Notes:

  1. Extended workflow works best in cases then the client implements SSO-like mechanism of authenticating the user via Fitbit. So if the user lost his session cookie with the client, he wouldn't go through login process, but his identity will be authenticated via Fitbit OAuth process instead. 

 

Request

REDIRECT to https://www.fitbit.com/oauth/authenticate?oauth_token=<temporary-token>[&locale=<locale>][&display=touch]

Example:

Request

The user approves the client application, and Fitbit redirects the user to the client application site.

(OAuth Flow Diagram D)

Request

User authorizes client access to the user's data on Fitbit:

POST http://www.fitbit.com/oauth/oauth_allow from the user's browser.

Response

oauth_callbackprovided in previous call?

Action:

yes

Redirect to (the value of) oauth_callback.

no

Redirect to callback URL provided at registration.

body

oauth_token=<temporary-token>&oauth_verifier=<verifier-string>

Example:
User authorizes client access to the user's data.

Response

The user approves the client application. The client application cannot receive redirects. Fitbit shows the verifier to the user on the Fitbit site.

(OAuth Flow Diagram D)

The OAuth Spec refers to an application which is not running as a web service and cannot receive a response via a callback as a Desktop application (as opposed to Browser). An iPhone app, for example, is an OAuth Desktop application, since running a web service on an iPhone is currently not viable (although custom URI could be used to provide callback as an alternative).

When an application is registered to be of type Desktop, or if a callback URL is not provided at registration or via oauth_callback, Fitbit shows the verifier to the user on a page on the Fitbit site. The client application is expected to provide a form where the user can enter the verifier.

Request

User authorizes client access to the user's data on Fitbit:

POST http://www.fitbit.com/oauth/oauth_allow from the user's browser.

Response

Fitbit shows the verifier on the page.


The client requests and receives token credentials from Fitbit.

(OAuth Flow Diagram E and F)

Request

POST /oauth/access_token

Authorization header parameters required in alphabetical order:

oauth_consumer_key

The client key agreed upon at registration.

oauth_token

Temporary token received previously.

oauth_nonce

Random string uniquely generated by client to allow the server to verify uniqueness of request.

oauth_signature

Signature calculated as described in The OAuth 1.0 Protocol Section 3.4: Signature.

oauth_signature_method

Signature method: HMAC-SHA1, RSA-SHA1, PLAINTEXT, etc.

oauth_timestamp

Timestamp

oauth_verifier

Verifier received when user authorized this client application.

oauth_version

1.0

When signing this request with HMAC-SHA1, you must use the temporary oauth_token_secret value obtained from the /oauth/request_token request. More

Response

status code:

200 OK

header:

Content-Type: application/x-www-form-urlencoded

body:

oauth_token=<access-token>&oauth_token_secret=<access-token-secret>

Example:

Request
Signature Base String
Response
Body

Using token credentials, the client makes calls to access Fitbit resources on behalf of the user.

(OAuth Flow Diagram G)

Request

GET <resource-URL>

Authorization header parameters required in alphabetical order:

oauth_consumer_key

The client key agreed upon at registration.

oauth_token

Access token received previously.

oauth_nonce

Random string uniquely generated by client to allow the server to verify uniqueness of request.

oauth_signature

Signature calculated as described in The OAuth 1.0 Protocol Section 3.4: Signature.

oauth_signature_method

Signature method: HMAC-SHA1, RSA-SHA1, PLAINTEXT, etc.

oauth_timestamp

Timestamp

oauth_version

1.0

Response

status code:

200 OK

header:

Content-Type: application/x-www-form-urlencoded

body:

Response in format requested: JSON or XML.

Example:

Request
Signature Base String
Response

(Also see Resource Access API: Activities.)

The OAuth Flow

Fitbit strictly follows the OAuth flow described in The OAuth 1.0 Protocol (draft-hammer-oauth-10):

  1. The client acquires a key and secret from Fitbit by registering an application at dev.fitbit.com.
  2. The client builds an application which uses content from Fitbit.
  3. The user requests to view content in the client application.
  4. The client requests and receives temporary credentials from Fitbit. A and B
  5. The client redirects the user to Fitbit in order for the user to authorize the client application. C
  6. The user approves the client application, and Fitbit redirects the user to the client application site, passing a verifier. D
  7. The client requests and receives token credentials from Fitbit using the verifier it received. E and F
  8. Using token credentials, the client makes calls to access Fitbit resources on behalf of the user. G

The following diagram from oauth.net details the flow (using original terms):

Terminology

Fitbit strictly follows the terminology listed in The OAuth 1.0 Protocol:

client:  Refers interchangeably to your application, or an HTTP client running in your application capable of making OAuth-authenticated requests, and your entity (i.e., you, your company, etc.).

server: The Fitbit service running at http://api.fitbit.com.

http://api.fitbit.com/<protected_resource>: Fitbit user content.

resource owner: Fitbit user.

credentials: A pair of key and matching secret. We refer to three class of credentials: clienttemporary, and token, used to identify and authenticate the client making the request, the authorization request, and  the access grant, respectively.

How to map original terms

We follow new terminology used in The OAuth 1.0 Protocol which maps to original community terms as follows (the term we use on the right in bold):

consumer:  client
consumer key and secret: client credentials
request token and secret: temporary credentials
access token and secret: token credentials

OAuth on the Web

There is plenty of information out there on OAuth. You can find specifications at:

RFC 5849, http://oauth.net, http://hueniverse.com/oauth/

Services such as TwitterLinkedInNetflixPhotoBucket, and Google also authenticate via OAuth and are good sources of information and provide links to third party and open source libraries.

Since there may be variations between OAuth implementations on different sites, we recommend that you start with information provided here, and later consult other sources of information on OAuth. 

  • No labels