Fitbit OAuth 2.0 Tutorial
This interactive tutorial shows how to access user data from the Fitbit Web API using the OAuth 2.0 protocol. For more details see the Developer Guide.
App Settings
First we need some settings for a registered application on dev.fitbit.com/apps.
Which type should I use?
- Apps that use a server to access the Fitbit Web API should use the Server type. This includes server-side web apps and mobile apps with a server component. Server apps are required to use the Client Secret to authenticate.
- Apps that directly access the API from client-side code should use the Client type. These are also known as public OAuth clients. These apps cannot securely store the Client Secret in client-side code and should generally not use it.
- The Personal type is limited to accessing the developer's own account and may use either option in this tutorial.
Getting an Access Token
Accessing user data requires an Access Token. Here we will step through the process of asking a user to authorize your app and retrieving the token.
Step 1: Generate PKCE and State Values
For optimal security Fitbit recommends using the Proof of Key for Code Exchange (PKCE) and State aspects of the OAuth protocol. This entails having your app generate three unique values for each authorization request. Click the Generate buttons below to generate sample values.
Tip: The PKCE Code Challenge can be tricky to compute. Paste a value into the above verifier field to see the correct challenge. See the Developer Guide for more details.
Step 2: Display Authorization Page
The next step is to display Fitbit's Authorization web page to the user. The URL for this should include the PKCE Code Challenge, State and the requested permission scopes.
For this tutorial you may simply click on the above link and log in with the Fitbit account you'd like to access. Select the scopes you'd like to grant and click Allow.
Step 3: Handle the Redirect
After the user clicks Allow on the authorization page their browser will be redirected
to the Redirect URL specified in Application Settings.
This is an endpoint your app should implement to receive two added query parameters:
code and state.
Tip: If your app hasn't implemented this endpoint yet and you see an error or empty page in your browser, the URL should still contain the needed query params. For this tutorial you can simply copy and paste the URL below and we will extract the params.
If you included state in the Authorization URL, verify the value returned here matches
the original. This helps ensure the redirect request originated with your app.
Step 4: Get Tokens
Now your app must exchange the authorization code for a pair of Access and Request Tokens. Here we will construct the HTTP request the app should make to the Token endpoint. This is also where the PKCE Code Verifier comes into play, which helps ensure tokens are delivered only to the app that requested them.
Apps of type "client" that omit the Client Secret must use PKCE. Make sure you generated a Code Challenge in step 1.
Server apps must pass an Authorization header with their
Basic Token, which is their
Client ID and Secret formatted like so:
"Basic " + base64encode(client_id + ":" + client_secret).
Step 5: Check Scopes
Finally the app should check which of the requested scopes the user actually granted. This
is noted in the scopes field of the previous step's response. If the user did not
grant a certain scope your app should not attempt to access the API endpoints that require it.
Access User Data
With an Access Token your app may start requesting user data.
Refresh Tokens
After the Access Token expiration time has passed your requests will receive a 401 HTTP error. When this happens, your app should use the Refresh Token to get a new pair of tokens.
