Skip to main content
Need help with your Fitbit integration? Pop into our Discord if you have questions or want to discover how Open Wearables can solve your problems.

​
Overview

Fitbit provides access to workout/activity data from Fitbit devices through the Fitbit Web API. The integration uses OAuth 2.0 for authentication and pull-based syncing to fetch activity data.

​
Supported data types

Data TypeSupport
Workouts / ActivitiesYes
SleepAvailable via API - not yet implemented
Heart rate (intraday)Available via API - not yet implemented
Daily activity summaryAvailable via API - not yet implemented
Open Wearables currently syncs workout/activity data from Fitbit using the Activities List API. Heart rate, sleep, and daily activity summary support is planned for a future release.

​
Data delivery

MethodDescription
Polling (pull)Open Wearables periodically fetches activity data via the Fitbit Web API (via Celery Beat)
Fitbit Subscription (webhook) support is out of scope for the current integration and remains tracked in GitHub issue #226. All sync is currently polling-based.

​
What you need by the end

  • App credentials: Client ID + Client Secret from the Fitbit Developer portal
  • Redirect URI registered in your Fitbit application

​
Prerequisites

  • A Fitbit account (any Fitbit user account can access the Developer portal)

​
Application walkthrough

1

Create a Fitbit Developer account

Go to dev.fitbit.com and sign in with your Fitbit account credentials.No separate developer account is required — your regular Fitbit account grants access to the Developer portal.
2

Register your application

Navigate to dev.fitbit.com/apps/new to register a new application.Fill in the registration form:
  • Application Name: Your app name (e.g. “Open Wearables”)
  • Description: Brief description of your application
  • Application Website URL: Your app’s website (can be http://localhost:3000 for local dev)
  • Organization: Your organization name
  • Organization Website URL: Your organization’s website
  • Terms of Service URL: URL to your terms (can be the same as Application Website for local dev)
  • Privacy Policy URL: URL to your privacy policy (can be the same as Application Website for local dev)
  • OAuth 2.0 Application Type: Select Personal for development and testing, or Server for production deployments
  • Redirect URL: For local development use http://localhost:8000/api/v1/oauth/fitbit/callback
  • Default Access Type: Select Read Only
Click Register to create your application.
After registration, your Client ID and Client Secret are shown on the application detail page. Store the Client Secret securely — it cannot be recovered if lost and you would need to generate new credentials.
3

Configure credentials in Open Wearables

Add the following to your .env file:
#--- Fitbit ---#
FITBIT_CLIENT_ID=your-fitbit-client-id
FITBIT_CLIENT_SECRET=your-fitbit-client-secret
FITBIT_REDIRECT_URI=http://localhost:8000/api/v1/oauth/fitbit/callback
# Optional: override default OAuth scopes (default: "activity heartrate sleep profile")
FITBIT_DEFAULT_SCOPE="activity heartrate sleep profile"
Configuration details:
VariableDescriptionDefault
FITBIT_CLIENT_IDClient ID from the Fitbit Developer portal—
FITBIT_CLIENT_SECRETClient Secret from the Fitbit Developer portal—
FITBIT_REDIRECT_URIMust match the Redirect URL registered in your Fitbit application. For local dev: http://localhost:8000/api/v1/oauth/fitbit/callbackhttp://localhost:8000/api/v1/oauth/fitbit/callback
FITBIT_DEFAULT_SCOPESpace-separated list of OAuth scopes to request. Only activity is actively synced at this time; reduce the scope to minimize consent surface if desired.activity heartrate sleep profile
Only activity data is actively synced at this time. You can reduce the requested consent surface by setting FITBIT_DEFAULT_SCOPE="activity".
4

Connect a user via OAuth

With credentials configured and your Open Wearables instance running, initiate the OAuth flow to connect a user’s Fitbit account.1. Get the authorization URL:
curl -X GET "http://localhost:8000/api/v1/oauth/fitbit/authorize?user_id={user_id}&redirect_uri=http://localhost:3000/users/{user_id}" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"
Response:
{
  "authorization_url": "https://www.fitbit.com/oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=activity+heartrate+sleep+profile&state=...",
  "state": "abc123..."
}
2. Redirect the user to the authorization_url. They will log in to Fitbit and authorize your app.3. Fitbit redirects back to the callback URI configured in your .env (FITBIT_REDIRECT_URI). Open Wearables automatically exchanges the authorization code for access tokens.4. Verify the connection was created:
curl -X GET "http://localhost:8000/api/v1/users/{user_id}/connections" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"
You should see a connection with "provider": "fitbit" and "status": "active".
The redirect_uri parameter in the authorize call is where the user is sent after the flow completes (e.g., back to your app). This is separate from FITBIT_REDIRECT_URI in your .env, which is the server-side OAuth callback that Fitbit sends the authorization code to.
5

Sync data

An initial sync is triggered automatically after a successful OAuth connection. To manually trigger a sync:
# Sync workouts/activities
curl -X POST "http://localhost:8000/api/v1/providers/fitbit/users/{user_id}/sync?data_type=workouts" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"
By default, Open Wearables syncs activities from the last 30 days. You can specify a custom date range using the start_date and end_date query parameters.
6

Verify the integration

Once data has synced, fetch it via the Open Wearables API:
# Fetch workouts
curl -X GET "http://localhost:8000/api/v1/users/{user_id}/events/workouts?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"
If workout data is returned, your Fitbit integration is working end-to-end.

​
Rate Limits

The Fitbit Web API enforces rate limits on a per-user, per-application basis:
LimitValue
Per hour (per user)150 requests
When the rate limit is exceeded, the API returns HTTP 429 Too Many Requests. The Fitbit-Rate-Limit-Reset response header indicates when the limit resets (Unix timestamp).

​
Next Steps

API Reference

Explore the Open Wearables API endpoints.

Architecture

Understand the overall system architecture.

​
Support

Need Help?