Public API overview
Public API overview
DistantRace exposes a REST API (/api/v1/) used by the mobile app, partner integrations, and whitelabel platforms. This is a high-level map — not a full OpenAPI reference.
Integration support
API access for third-party development is typically arranged with DistantRace support. Authentication and rate limits apply.
Base URL #
https://distantrace.com/api/v1/
Authentication #
| Grant / token | Typical caller | Scope |
|---|---|---|
| Session / mobile token | DistantRace app, logged-in web | User-scoped read/write |
Org token (client_credentials) |
Whitelabel portal backend | Public listings, join-code validate/redeem, hero images |
| User OAuth (authorization code + refresh) | Whitelabel SPA after sign-in | Join, workouts, profile, checkout |
Whitelabel integrations use two credential types:
| Credential | Use |
|---|---|
| Org token (long-lived bearer) | Public event/challenge listings, hero images, join-code validation, email-token redemption |
| User OAuth client (authorization code) | Participant sign-in, join events, workouts, profile, checkout |
The org token is resolved from the OAuth application owner — every whitelabel API call is implicitly scoped to one club.
Account endpoints include login QR, social login, profile (/api/v1/account/me/), and device registration.
See Whitelabel and enterprise setup for the full participant-portal model.
Whitelabel join-code flows #
| Endpoint | Method | Purpose |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Check whether a code is active for your org; returns public event payload (no participant PII) |
event/joincode/redeem-email-token/ |
POST | Consume a magic-link token from an invitation email; returns OAuth tokens and may auto-enrol in a challenge |
event/joincode/ |
POST | Create a join code and send invitation email (admin user token only — not the public org token) |
Magic-link redemption uses the org token plus a single-use token in the POST body. The server may create a user from join-code prefill data, issue access/refresh tokens, and call auto-enrol when the code is bound to a challenge.
Hero images (whitelabel only) #
GET orgs/hero-images/?language=<code> — active carousel images for the token's organization. Requires is_whitelabel on the club. Optional language filter returns locale-specific images plus language-neutral fallbacks.
Main resource groups #
| Prefix | Resources |
|---|---|
event/ |
Events, join codes, posts |
gamification/ |
Challenges, challengers, team challenges, goals, daily stats |
races/ |
Competitions, entrants (racers), results |
shop/ |
Carts, cart items, products, premium levels |
users/ |
Users, participants, push devices |
workouts/ |
Activities, upload, sport/kind metadata |
orgs/ |
Organizations, hero images (whitelabel) |
finances/ |
Payment channels, pricing helpers |
Common integration tasks #
| Task | Typical endpoints |
|---|---|
| List published events | event/event/ |
| Register participant | races/registration/entrant/ |
| Sync activities | workouts/ or workouts/upload/ |
| Read results | races/result/ |
| Mobile daily steps | gamification/dailystat/ |
Enterprise SSO #
SAML endpoints (platform auth host):
| Path | Purpose |
|---|---|
/saml2/discovery/ |
Enter work email → route to the correct IdP by domain |
/saml2/login/ |
Start SAML authentication (optional idp and next query params) |
/saml2/acs/ |
Assertion consumer (IdP callback) |
/saml2/metadata/ |
Service-provider metadata for IdP configuration |
When multiple identity providers exist, discovery matches the email domain to an IdP before redirecting to login. With a single IdP, discovery skips straight to /saml2/login/.
Participant and staff flows: Enterprise SAML and whitelabel login.
Data export alternative #
For one-off spreadsheets without coding, use manager exports — Organizer documents, Exporting results data, Yearly income export.