Distantrace Docs
Sprog · 14
Latviešu Latvian lv English English en Deutsch German de Polski Polish pl Français French fr Español Spanish es Italiano Italian it Português Portuguese pt Svenska Swedish sv Norsk Norwegian no Dansk Danish dk Nederlands Dutch nl Türkçe Turkish tr العربية Arabic ar
Åbn appen

Whitelabel and enterprise setup

7 min læsning Opdateret Jul 2026 14 sprog

Endnu ikke oversat

Denne side er endnu ikke tilgængelig på dit sprog — viser den engelske version.

Whitelabel and enterprise setup

Some clubs run DistantRace on a whitelabel deployment: a branded participant portal on a custom domain, connected to the same organizer console and event data on DistantRace.

Whitelabel is a platform-managed offering. DistantRace enables the club flag, OAuth credentials, themed login pages, custom-domain hosting, and SAML identity providers. Organizers continue to create events and manage participants in the manager console as usual.

Contact DistantRace support to discuss whitelabel for your organization.

What whitelabel enables #

Capability Participant experience Organizer / platform
Custom domain Browse and register at your club URL (e.g. events.yourcompany.com) DNS + TLS provisioned by DistantRace; domain verified via Embed domains
Branded portal Club name, logo, colors, and localized UI chrome SPA branding configured at deploy time; event content still comes from DistantRace
Themed login Login and account pages match your brand during OAuth domain_theme templates on the DistantRace auth host
OAuth participant login Sign in on your portal; session persists in the browser Authorization-code OAuth2 app scoped to your organization
Org API token Public listings (events, challenges, leaderboards) without login Long-lived read token for the branded site backend
Hero images API Carousel banners on the portal home page Club branding and hero images — available when is_whitelabel is enabled
SAML / enterprise SSO Sign in with work email via Microsoft Entra ID or other IdP Per-domain IdP mapping; discovery at /saml2/discovery/ — see Enterprise SAML and whitelabel login
Branded email Login codes and transactional mail from your sender SendGrid integration on the club
Join codes & invites Redeem codes and email invitation links on the branded site Same join codes as distantrace.com; magic-link auto-enrol via API
Sport app connections Connect Garmin, Strava, step sources, etc. OAuth connect flows run on the canonical DistantRace auth host, then return to your portal
REST API Full participant actions after login (join, sync workouts, profile) Same /api/v1/ surface as the mobile app — Public API overview
Manager console N/A — organizers use distantrace.com Unchanged; Two-factor authentication still required

Platform vs. portal scope

A whitelabel participant portal is a focused front end on top of the DistantRace API. Which screens are exposed (challenges only, competitions with checkout, team leaderboards, etc.) depends on the deployment. All underlying event types and settings are configured in the manager console.

How it fits together #

flowchart LR
  subgraph portal [Branded participant portal]
    SPA[Custom domain SPA]
  end
  subgraph drace [DistantRace platform]
    API["/api/v1/"]
    Auth[OAuth + themed login]
    Console[Manager console]
    SAML[SAML discovery]
  end
  SPA -->|org token — public data| API
  SPA -->|user token — after login| API
  SPA -->|redirect| Auth
  Auth --> SAML
  Console --> API
  1. Participant portal — a web app on your domain. It loads public event data with an organization-scoped API token and sends participants to DistantRace OAuth for login.
  2. DistantRace auth — handles login codes, OAuth, SAML, and sport-app connections. Themed templates apply when the OAuth request includes your organization context.
  3. Manager console — organizers create challenges, competitions, tickets, and marketing on distantrace.com. Changes appear on the branded portal through the API.

Setup (platform-managed) #

DistantRace typically handles:

Item Details
is_whitelabel club flag Unlocks hero-image management and the hero-images API
OAuth applications User client (authorization code) for participant login; org token for public listings
domain_theme Selects branded login/signup templates on the auth host
Custom domain hosting TLS certificate, ingress, and optional *.wl.distantrace.com staging hostname (matches your domain_theme slug)
SAML identity providers SAMLIdentityProvider records mapped to email domains
Portal deployment Branded SPA build, cache proxy, and CI/CD on the whitelabel infrastructure

What organizers configure themselves #

Task Where
Events, tickets, join codes Manager console — same as any club
Hero images for the portal carousel Marketing → Hero images (whitelabel clubs only)
Embed / custom domains Club → Embed domains — Embed domains for iframes
Branded email sender Club → Integrations → SendGrid
Club logo Club → Settings
Disable daily overview emails Club-level or per-challenge setting (whitelabel clubs)

Participant login flows #

Whitelabel portals commonly use OAuth authorization code:

  1. Participant clicks Sign in on the branded site.
  2. Browser redirects to DistantRace /oauth/authorize/ with your organization's UUID.
  3. DistantRace shows a themed login page (email code, passkey, or SAML — depending on club configuration).
  4. After authentication, the browser returns to your portal with a code exchanged for access and refresh tokens.
  5. The portal calls /api/v1/ with the user token for personal actions (join challenge, sync workouts, update profile).

Email invitation links can auto-log participants in via the redeem-email-token API endpoint when the portal is configured with an org token.

SAML SSO is available for enterprise clubs. Participants enter a work email; DistantRace routes to the correct IdP by domain. See Enterprise SAML and whitelabel login.

API credentials (overview) #

Whitelabel integrations use two credential types:

Credential Grant / type Typical use
Org token Long-lived bearer token (org admin user) Public challenge/event listings, hero images, join-code validation, email-token redemption
User OAuth client Authorization code (+ refresh token) Participant sign-in, join events, workouts, profile, checkout

Both are created and rotated by DistantRace during onboarding. Redirect URIs must match your portal's /auth/callback path on each environment (staging *.wl.distantrace.com and production custom domain).

OAuth authorize URL #

Participant sign-in starts at /oauth/authorize/ with:

  • client_id — your user OAuth application
  • redirect_uri — registered callback on your portal
  • response_type=code
  • org=<club-uuid> — binds the login page to your organization and selects the themed template

After the participant authenticates (email code, passkey, or SAML), DistantRace redirects to your callback with an authorization code. Exchange it server-side or in the SPA for access and refresh tokens.

Join codes and invitation emails #

Step API
Validate a code before showing checkout GET /api/v1/event/joincode/{code}/validate/ (org token)
Redeem email magic link POST /api/v1/event/joincode/redeem-email-token/ with { "token": "…" }
Create codes from your back office POST /api/v1/event/joincode/ (admin user token — not the public org token)

Magic-link redemption can auto-create an account from join-code prefill data, return OAuth tokens, and auto-enrol the participant in a bound challenge when configured.

Full endpoint map: Public API overview.

Email and notifications #

When SendGrid is connected:

  • Login code emails use your org's transactional template and sender address.
  • Registration and marketing templates follow the same integration.

Whitelabel clubs can suppress the automated Daily Overview email for step challenges at the organization level (daily_email_disabled) or per challenge.

Mobile app #

The standard DistantRace mobile app remains available. Participants can connect sport apps and sync steps through the app even when they register on a branded web portal. The app is not white-labeled; account data is shared across distantrace.com, the mobile app, and the branded portal.

Organizer access #

Organizers and staff continue to use the manager console at distantrace.com:

  • URL pattern: /console/<org-code>/
  • Two-factor authentication is required
  • SAML may be used for staff login on enterprise clubs, but console access is separate from the participant portal OAuth flow

See How to access the organizer console.

← Forrige Mobile ticket scanning for organizers

Vis som Markdown