---
title: Public API overview
description: REST API endpoints for mobile apps, integrations, and whitelabel platforms
order: 5
---

# 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.

::: warning 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](../running-events/whitelabel-and-enterprise-setup.md) 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](../joining-events/enterprise-saml-and-whitelabel-login.md).

## Data export alternative

For one-off spreadsheets without coding, use manager **exports** — [Organizer documents](organizer-documents.md), [Exporting results data](../results/exporting-results-data.md), [Yearly income export](../finance-module/yearly-income-export.md).

## Related

- [Whitelabel and enterprise setup](../running-events/whitelabel-and-enterprise-setup.md)
- [How to export data from DistantRace](how-to-export-data-from-distantrace.md)
- [Integrations](../integrations/introduction-to-integrations.md)