Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3


The Fitbit API uses OAuth Authentication as described in The OAuth 1.0 Protocol (draft-hammer-oauth-10). 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.

...

  • 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)

Anchor
Request
Request
Request

POST /oauth/request_token

...

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleRequest
borderStylesolid
titleRequest

POST /oauth/request_token HTTP/1.1
Host: api.fitbit.com
Authorization: OAuth oauth_consumer_key="fitbit-example-client-application",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1270248082",
oauth_nonce="161822064",
oauth_callback="http%3A%2F%2Fexample.fitbit.com%2Fapp%2FcompleteAuthorization",
oauth_signature="Omf%2Bls2gn%2BDlghq245LRIyfMdd8%3D"
oauth_version="1.0"
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
borderStylesolid
titleSignature Base String
borderStylesolid
POST&http%3A%2F%2Fapi.fitbit.com%2Foauth%2Frequest_token&oauth_callback%3Dhttp%253A%252F%252Fexample.fitbit.com%252Fapp%252FcompleteAuthorization%26oauth_consumer_key%3Dfitbit-example-client-application%26oauth_nonce%3D161822064%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1270248082%26oauth_version%3D1.0
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleResponse
borderStylesolid
titleResponse

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleBody
borderStylesolid
titleBody

oauth_token=c5a8b2ff2a20524381083b1fe172fdc1&oauth_token_secret=8508e7c450fc2462ae4932fa63c35b30&oauth_callback_confirmed=true

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

(OAuth Flow Diagram C)

Request

...

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

Code Block
REDIRECT to [https://www.fitbit.com/oauth/authorize?oauth_token=c5a8b2ff2a20524381083b1fe172fdc1]

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:

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleRequest
borderStylesolid
titleRequest

REDIRECT to [httphttps://www.fitbit.com/oauth/authorizeauthenticate?oauth_token=c5a8b2ff2a20524381083b1fe172fdc1]

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:

...

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleResponse
borderStylesolid
titleResponse

REDIRECT to [http://example.fitbit.com/app/completeAuthorization?oauth_token=c5a8b2ff2a20524381083b1fe172fdc1&oauth_verifier=car3fbtjvralpv4kvba65arls2]

...

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 client Desktop application (as opposed to web Browser). An iPhone app, for example, is an OAuth client 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 client 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.

...

The client requests and receives token credentials from Fitbit.

(OAuth Flow Diagram E and F)

Request

POST /oauth/access_token

...

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>

...

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleRequest
borderStylesolid
titleRequest

POST /oauth/access_token HTTP/1.1
Host: api.fitbit.com
Authorization: OAuth oauth_consumer_key="fitbit-example-client-application",
oauth_token="c5a8b2ff2a20524381083b1fe172fdc1",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1270248088",
oauth_nonce="707915577",
oauth_verifier="car3fbtjvralpv4kvba65arls2",
oauth_signature="60tu0BfKRfXSlPpeBzzb0DOiIoA%3D"
oauth_version="1.0"
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
borderStylesolid
titleSignature Base String
borderStylesolid
POST&http%3A%2F%2Fapi.fitbit.com%2Foauth%2Faccess_token&oauth_consumer_key%3Dfitbit-example-client-application%26oauth_nonce%3D707915577%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1270248088%26oauth_token%3Dc5a8b2ff2a20524381083b1fe172fdc1%26oauth_verifier%3Dcar3fbtjvralpv4kvba65arls2%26oauth_version%3D1.0
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleResponse
borderStylesolid
titleResponse

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleBody
borderStylesolid
titleBody

oauth_token=8d3221fb072f31b5ef1b3bcfc5d8a27a&oauth_token_secret=894fa2bec6f6acc570b80135218656f5&encoded_user_id=228TQ4

...

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

(OAuth Flow Diagram G)

Request

GET <resource-URL>

...

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleRequest
borderStylesolid
titleRequest

GET /1/user/-/activities/date/2010-04-02.json HTTP/1.1
Host: api.fitbit.com
Authorization: OAuth oauth_consumer_key="fitbit-example-client-application",
oauth_token="8d3221fb072f31b5ef1b3bcfc5d8a27a",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1270248088",
oauth_nonce="515379974",
oauth_signature="Gf5NUq1Pvg3DrtxHJyVaMXq4Foo%3D"
oauth_version="1.0"
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
borderStylesolid
titleSignature Base String
borderStylesolid
GET&http%3A%2F%2Fapi.fitbit.com%2F1%2Fuser%2F-%2Factivities%2Fdate%2F2010-04-02.json&oauth_consumer_key%3Dfitbit-example-client-application%26oauth_nonce%3D515379974%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1270248088%26oauth_token%3D8d3221fb072f31b5ef1b3bcfc5d8a27a%26oauth_version%3D1.0
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
titleResponse
borderStylesolid
titleResponse

{
    "activities":[],
    "goals":{
        "activeScore":1000,
        "caloriesOut":2826,
        "distance":8.05,
        "floors":150,
        "steps":10000
     },
    "summary":{
        "activeScore":2,
        "activityCalories":230,
        "caloriesOut":1343,
        "distances":[
            {"activity":"tracker", "distance":1.32},
            {"activity":"loggedActivities", "distance":0},
            {"activity":"total","distance":1.32},
            {"activity":"veryActive", "distance":0.51},
            {"activity":"moderatelyActive", "distance":0.51},
            {"activity":"lightlyActive", "distance":0.51},
            {"activity":"sedentaryActive", "distance":0.51}
        ],
        "fairlyActiveMinutes":0,
        "lightlyActiveMinutes":0,
        "marginalCalories":200,
        "sedentaryMinutes":1166,
        "steps":0,
        "veryActiveMinutes":0
    }
}

...

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 . Currently, this is handled via Out of Band (oob) communication, e.g., email.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 (draft-hammer-oauth-10):

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.).

...

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
Anchor
Howtomaporiginalterms
Howtomaporiginalterms

...

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:

http://tools.ietf.org/html/draft-hammer-oauth-10RFC 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.