How to Integrate the Wahoo Cloud API (2026)

Wahoo's Cloud API connects Wahoo users to your app over OAuth 2.0 and covers profile data, heart rate and power zones, routes, plans and the upload and download of workouts. It is separate from Wahoo's iOS and Android APIs. Everything below is from Wahoo's developer portal, its live Cloud API documentation and its Public API Agreement, as read on October 17, 2026. If you are still choosing a provider, start with wearable data APIs.

Access and approval#

The agreement adds terms worth reading before you build: you may not charge end users for access to Wahoo's API materials or anything included in them, though you can charge for functionality Wahoo does not provide, and you must attribute Wahoo using the links and logos it supplies.

Auth and scopes#

Wahoo uses the OAuth 2.0 authorization-code flow, with PKCE available for public clients. Its base URL is api.wahooligan.com.

GET https://api.wahooligan.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.example.com/callback
  &scope=user_read%20workouts_read%20offline_data
  &response_type=code

Exchange the returned code with a POST to https://api.wahooligan.com/oauth/token carrying your client_id, client_secret, the code, your redirect_uri and grant_type=authorization_code. For PKCE, set your app's "Confidential?" field to No in the portal, send a code_challenge (Wahoo accepts plain or S256) and pass the code_verifier on the token and refresh calls instead of the secret.

The developer portal lists twelve scopes: email, user_read, user_write, power_zones_read, power_zones_write, workouts_read, workouts_write, plans_read, plans_write, routes_read, routes_write and offline_data. Two rules matter. Without user_read, Wahoo says the API returns 403. And offline_data, described as receiving data even when the app is closed, is required for webhooks. Request only what you use; Wahoo says applications must only request permission for resources they intend to access or modify.

Tokens need care:

• Access tokens expire after 2 hours. Refresh with grant_type=refresh_token to get a new access token and a new refresh token.
• Old tokens die on use, not on refresh. The previous access and refresh tokens are revoked once an API call is made with the refreshed token. Refreshing alone does not revoke anything.
• A cap per user. From January 1, 2026, an application is limited to 10 unrevoked access tokens per user, and unrevoked tokens are deleted automatically 60 days after creation. Wahoo's advice: refresh only immediately before an API request.
• File downloads do not count. Downloading a FIT file from Wahoo's CDN is not an API request, so it does not revoke previous tokens.

To disconnect a user, call DELETE https://api.wahooligan.com/v1/permissions. Portal flags can make that call, or a user revoking access from their account settings, also delete incomplete future workouts and the plans available to the user through your app.

Data: workouts, summaries, plans, routes and zones#

One limitation shapes what you can promise: Wahoo does not share completed workout data that originates from third-party applications, a change its changelog dates to April 1, 2025. A workout's fitness_app_id tells you the source: below 1000 is a Wahoo application, above 1000 a third party. Plans follow a library model, so create the plan once, then reference its ID from workouts; to show a plan on an ELEMNT bike computer it must be attached to a workout scheduled from today to six days out. The API returns decimal values as strings.

Webhooks#

Configure webhooks per app with three settings: webhook_enabled, webhook_url and a webhook_token that Wahoo sends with each call so you can ignore anything without it. The documented event is workout_summary, which arrives as a JSON POST with the summary, the user's ID, the workout and a FIT file URL, and it requires users to have granted offline_data.

If your endpoint does not return HTTP 200, Wahoo retries after 30 minutes, 4 hours, 24 hours and 72 hours. Duplicates are possible when files are updated or deleted, so make your handler idempotent.

Rate limits#

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, each listing the day, hour and 5-minute windows. The published limits:

Authentication, token refreshes and file downloads do not count against them. Wahoo asks you to contact support if you need more; a 429 means you are over.

What changed recently#

The token cap of 10 unrevoked access tokens per user took effect on January 1, 2026.

Gotchas and production notes#

• Plan two apps. Sandbox and Production are separate applications and a sandbox app cannot be promoted.
• Refresh late. Refresh right before a call and use the new token at once, or you will pile up unrevoked tokens against the per-user cap.
• No third-party workouts. Users who record in other apps will not see those workouts through Wahoo.
• Ask for user_read and offline_data. One is needed to avoid 403s, the other for webhooks.
• Error 422 can mean "not approved". Wahoo lists 422 for missing or invalid parameters or an app that is not approved.

The rest of the cluster is at how to integrate a fitness or health API.