Integration API

ShadoU API

Connect apps, devices, and services to ShadoU.

The ShadoU API allows developers and partner apps to read and write activity data, connect athlete accounts with OAuth 2.0, and build integrations around tracking, analytics, coaching, and social features.

What you can do

  • Connect external apps to a ShadoU account
  • Import activities into ShadoU
  • Export activity data from ShadoU
  • Read athlete profile and activity summaries
  • Sync workout data, posts, and selected account metadata
  • Build coaching, training, and analytics integrations

Supported integration methods

  • OAuth 2.0 authorization
  • GPX file import
  • Direct API integration
  • Future support may include FIT, TCX, and webhook-based sync

For Athletes

You can import activity files into ShadoU even if your device or app does not have a direct integration yet.

Import a GPX file

You can upload a GPX file manually from the web portal.

  1. Open Activity
  2. Select Import
  3. Choose your .gpx file
  4. Review the detected activity details
  5. Save the activity to your profile

What GPX import includes

  • route points
  • timestamps
  • distance path
  • elevation data when available

Depending on the source, GPX may not include

  • heart rate
  • cadence
  • power
  • stroke rate
  • advanced device metrics

GPX import notes

  • Large files may take longer to process
  • Elevation-based scoring depends on the quality of recorded altitude
  • Duplicate imports may be flagged
  • Invalid or corrupted files may be rejected

Best results

  • export directly from your recording device or trusted app
  • keep timestamps intact
  • avoid heavily edited route files
  • use files with accurate GPS and elevation data

For Developers

OAuth 2.0 with ShadoU

External apps can connect to ShadoU using OAuth 2.0. This allows a user to authorize your application to access their ShadoU account without sharing their password.

Typical OAuth flow

  1. Your app sends the user to the ShadoU authorization page
  2. The user signs in and approves requested permissions
  3. ShadoU redirects back to your application with an authorization code
  4. Your backend exchanges the code for an access token
  5. Your app uses the access token to call the ShadoU API

Supported grant type

  • Authorization Code
  • Authorization Code with PKCE is recommended for public clients and mobile apps

Recommended use cases

  • Mobile apps
  • Web apps
  • Coaching platforms
  • Analytics tools
  • Event and marketplace integrations

Typical scopes

profile:readactivities:readactivities:writesocial:readwallet:readcoaching:readcoaching:write

Only request the scopes your integration actually needs.

Register an App

To use OAuth 2.0, developers must register an application in the ShadoU developer area.

Registration includes

  • Application name
  • Description
  • Redirect URI(s)
  • App website
  • Contact email
  • Requested scopes

After registration

  • client_id
  • client_secret for confidential clients
  • environment details for authorization and token exchange

Redirect URI rules

  • Must exactly match a registered redirect URI
  • HTTPS is required for production
  • Localhost may be allowed in development

Security Requirements

  • Never expose a client secret in public frontend code
  • Use PKCE for mobile and public clients
  • Store tokens securely
  • Use HTTPS only
  • Request the minimum required scopes
  • Refresh and revoke tokens safely

Token handling

  • Access tokens are short-lived
  • Refresh tokens may be used if enabled for your app
  • Revoked or expired tokens must not be retried indefinitely

Activity Import API

Apps that have been authorized by a user may submit activity data to ShadoU through the API.

Expected import behavior

  • sport type
  • start time
  • duration
  • distance
  • route points
  • elevation
  • optional metrics such as heart rate, cadence, and power

Processing behavior

  • validated
  • normalized
  • scored using the ShadoU scoring engine
  • flagged if data appears invalid or unrealistic

Beta endpoint examples

POST /api/auth.php?action=register
POST /api/auth.php?action=login
GET /api/auth.php?action=me
POST /api/auth.php?action=create-token
POST /api/activities.php
curl -X POST https://shadou.top/api/activities.php \
  -H 'Authorization: Bearer shd_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "sport_type":"run",
    "started_at":"2026-04-12T06:00:00Z",
    "ended_at":"2026-04-12T06:42:16Z",
    "duration_seconds":2536,
    "distance_meters":8420,
    "source_app":"Partner App"
  }'

Rate Limits

  • reasonable per-user and per-app limits apply
  • burst abuse may be throttled
  • repeated invalid requests may be blocked

If your integration needs higher limits, contact ShadoU support.

Versioning

The API should be versioned to preserve stability.

/api/v1/...

Breaking changes should only be introduced in a new version.

Errors

200 OK201 Created400 Bad Request401 Unauthorized403 Forbidden404 Not Found429 Too Many Requests

Error responses should include a clear machine-readable code and a human-readable message.

Webhooks

  • new activity created
  • activity updated
  • coach booking events
  • wallet events
  • marketplace events

Need help?

If you are building an integration and need access, testing support, or higher limits, contact the ShadoU team through the developer support section.