> ## Documentation Index
> Fetch the complete documentation index at: https://openwearables.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Strava API Integration

> Connect Strava via OAuth 2.0 for activity sync. Webhooks for real-time events plus polling for historical data.

> [!NOTE]
>
> **Need help with your Strava integration?** Pop into our [Discord](https://discord.gg/qrcfFnNE6H) if you have questions or want to discover how Open Wearables can solve your problems.

## Overview

Strava provides access to activity/workout data through their API. The integration supports real-time webhook notifications for new activities as well as historical activity data via polling.

Each Open Wearables user can connect their own Strava account. Strava's Standard Tier allows up to **10 connected athletes** — upgradeable directly from your [API Settings Dashboard](https://www.strava.com/settings/api) without formal review. For more than 10 athletes, apply for Extended Access Tier.

> [!WARNING]
>
> **Strava subscription required (as of June 2026).** A Strava subscription is now required to access the API as a Standard Tier developer. If you registered before June 1, 2026 you have until June 30, 2026 to subscribe. Extended Access Tier developers are not affected.

### Supported data types

| Data Type | Support |
| - | - |
| Workouts / Activities | Yes |
| Sleep | No |
| Daily summaries (247 data) | No |
| Body composition | No |

Strava is an activity-focused platform — it does not provide continuous health monitoring data like sleep, HRV, or daily summaries.

### Data delivery

| Method | Description |
| - | - |
| **Webhooks (push)** | Strava sends real-time notifications for activity create/update/delete events, plus athlete deauthorization events |
| **Polling (pull)** | Historical activity data can be fetched via the API |

## Developer tiers

| Tier | Athletes | Rate limits | Subscription required |
| - | - | - | - |
| Standard | Up to 10 (self-upgrade) | 200 req/15 min, 2,000 req/day | Yes |
| Extended Access | Higher limits | 400 req/15 min, 4,000 req/day | No |

Self-upgrade to Standard Tier (up to 10 athletes) directly from your [API Settings Dashboard](https://www.strava.com/settings/api). For Extended Access, submit your app for review through the same dashboard.

## What you need by the end

* **App credentials**: Client ID + Client Secret
* **OAuth scopes** configured
* **Webhook subscription** created (so Strava sends activity events to your server)

## Prerequisites

* A Strava account (active subscription required for Standard Tier API access; Extended Access Tier is exempt)

## Application walkthrough

**1. Create a Strava API Application**

Log in to your Strava account and go to:

* [https://www.strava.com/settings/api](https://www.strava.com/settings/api)

Fill in the application form:

* **Application Name**: Your app name
* **Category**: Choose the category that best describes your app
* **Website**: Your app's website URL
* **Authorization Callback Domain**: `localhost` for local development, or your production domain (e.g. `yourdomain.com`)

> [!WARNING]
>
> The **Authorization Callback Domain** is just the domain, not the full URL. For local development, use `localhost`. Do not include the port or path.

After creating the app, you'll receive:

* **Client ID**
* **Client Secret**

> [!WARNING]
>
> Treat the Client Secret like a password. Store it in your secrets manager and rotate if compromised.

**2. Configure credentials in Open Wearables**

Add the following to your `.env` file:

```bash theme={null}
# Public base URL of your API. The OAuth redirect URI is derived from this as
# {API_BASE_URL}/api/v1/oauth/strava/callback.
API_BASE_URL=http://localhost:8000

#--- Strava ---#
STRAVA_CLIENT_ID=your-strava-client-id
STRAVA_CLIENT_SECRET=your-strava-client-secret
STRAVA_DEFAULT_SCOPE=activity:read_all,profile:read_all
# STRAVA_WEBHOOK_VERIFY_TOKEN=  # optional: derived from SECRET_KEY when unset
```

**Configuration details:**

| Variable | Description |
| - | - |
| `API_BASE_URL` | Public base URL of your API. The OAuth redirect URI is derived from it as `{API_BASE_URL}/api/v1/oauth/strava/callback`. Its domain must match the Authorization Callback Domain you set in Strava |
| `STRAVA_CLIENT_ID` | Client ID from the Strava API settings page |
| `STRAVA_CLIENT_SECRET` | Client Secret from the Strava API settings page |
| `STRAVA_DEFAULT_SCOPE` | OAuth scopes requested during authorization. Default `activity:read_all,profile:read_all` covers all activity data and athlete profile |
| `STRAVA_WEBHOOK_VERIFY_TOKEN` | Optional. Strava sends this back during webhook subscription verification to confirm ownership. When unset, it is derived from `SECRET_KEY`, so Strava never receives `SECRET_KEY` itself |

> [!NOTE]
>
> Strava signs its webhook events with a key it does not share, so Open Wearables cannot check the signature. Instead, the callback URL carries a secret derived from `SECRET_KEY`, which authenticates each event. In addition, before deleting an activity or disconnecting an athlete, Open Wearables confirms the change in the Strava API.

**3. Create a webhook subscription**

To receive real-time activity notifications, Strava needs a webhook subscription pointing at your Open Wearables instance. Your server must be publicly accessible over HTTPS. For local development, use a tunneling tool like [ngrok](https://openwearables.io/docs/dev-guides/ngrok-setup.md).

In your Open Wearables dashboard, go to **Settings → Providers**, find **Strava**, and switch its live sync mode from **Periodic pull** to **Webhook**. Open Wearables registers the subscription in the background with this callback URL:

```
{API_BASE_URL}/api/v1/providers/strava/webhooks/{callback token}
```

The callback token is derived from `SECRET_KEY` and is not shown anywhere. Strava sends a `GET` handshake to that URL; Open Wearables checks the token in the path and the `hub.verify_token` parameter, and echoes back `hub.challenge` to confirm the subscription. Requests without the token, or with a wrong one, are rejected with `401`.

After a new `SECRET_KEY` or `API_BASE_URL`, register the subscription again with `POST /api/v1/providers/strava/webhooks/subscriptions` (see [provider webhook subscriptions](https://openwearables.io/docs/api-reference/guides/provider-webhook-subscriptions.md)). Strava allows only **one subscription per application** and its callback URL cannot be changed, so Open Wearables deletes the old subscription and creates a new one; for Strava, the `callback_url` parameter is ignored. Instances upgrading from a version without the token do this once on their own at startup.

> [!WARNING]
>
> Treat the callback URL like a password. Anyone who knows it can send events in Strava's name, though deletes and deauthorizations are still confirmed in the Strava API. Open Wearables masks the token in its logs, in Sentry, and in the subscription list, but your reverse proxy's access logs record full request paths. If the URL leaks, rotate `SECRET_KEY`, restart, and register the subscription again. A new `SECRET_KEY` also invalidates issued access tokens (refresh tokens stay valid, so sessions renew), and changes the webhook secrets derived from it (Google Health, Oura, Suunto) unless those are set explicitly, so those providers need their subscriptions or portal settings updated too.

**4. Verify the integration**

Once everything is configured:

1. Start your Open Wearables instance
2. Connect a Strava account through the OAuth flow
3. Create or record an activity on Strava
4. The webhook should deliver the event and Open Wearables will fetch and store the full activity data

## OAuth Scopes Reference

| Scope | Description |
| - | - |
| `activity:read` | Read public activities |
| `activity:read_all` | Read all activities (including private) |
| `profile:read_all` | Read athlete profile |

The default scope `activity:read_all,profile:read_all` is recommended for full activity data access.

## Next Steps

> [card] [API Reference](https://openwearables.io/docs/api-reference/introduction.md)
>
> Explore the Open Wearables API endpoints.

> [card] [Architecture](https://openwearables.io/docs/architecture/system-overview.md)
>
> Understand the overall system architecture.

## Support

> [!NOTE]
>
> **Need Help?**
>
> * Join our [Discord](https://discord.gg/qrcfFnNE6H) and ask a question.
> * Check [GitHub Discussions](https://github.com/the-momentum/open-wearables/discussions).
> * Check the [Strava API Documentation](https://developers.strava.com/docs/reference/).
> * Check the [Strava Webhook Documentation](https://developers.strava.com/docs/webhooks/).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.