Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


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 implementationSearch for an OAuth 1.0a library for your language and framework of choice. We have a short list of ones we know other developers have used. You don't need to read the rest of this page if you find one.
  3. Seriously, you should use an established OAuth 1.0a library instead of trying to implement OAuth 1.0a on your own. You most definitely will not get it correct on your first attempt.
  4. You're still here. We warned you. Please study the OAuth Flow Diagram before continuing.
  5. Use the documentation here to implement authentication in your API client and application.
  6. Check out and play with Fitbit OAuth 1.0a debug tool

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)

Anchor
Request
Request
Request

POST /oauth/request_token

...

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

...

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
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

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
borderStylesolid
titleResponse

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
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.

Info

Fitbit serves the X-Frame-Options response header on all web pages to prevent clickjacking attacks. The OAuth authorization page must be displayed in a primary or pop-up browser window. It cannot be access via an iframe.

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
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:

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

Response

oauth_callback provided 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>

...

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
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.

Request

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

POST httphttps://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>

...

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
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

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
borderStylesolid
titleResponse

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

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

...

Anchor
tokenCredentials
tokenCredentials

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.

...

Code Block
bgColor#eeeeee
titleBGColor#3ec1c1
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

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
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
    }
}

(Also see Resource Access API: Activities.)

The OAuth Flow
Anchor
TheOAuthFlow
TheOAuthFlow

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

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

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

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

...

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

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:

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.