---
title: Öffentliche API-Übersicht
description: REST API-Endpunkte für mobile Apps, Integrationen und Whitelabel-Plattformen
order: 5
source_hash: bbd272c97e8f
slug: oeffentliche-api-uebersicht
---

# Öffentliche API-Übersicht

DistantRace bietet eine **REST API** (`/api/v1/`), die von der mobilen App, Partnerintegrationen und Whitelabel-Plattformen genutzt wird. Dies ist eine Übersicht auf hoher Ebene — keine vollständige OpenAPI-Referenz.

::: warning Integrationsunterstützung
Der API-Zugang für Drittentwicklungen wird in der Regel mit dem DistantRace-Support arrangiert. Authentifizierung und Ratenbegrenzungen gelten.
:::

## Basis-URL

```
https://distantrace.com/api/v1/
```

## Authentifizierung

| Grant / Token | Typischer Anrufer | Umfang |
|---------------|-------------------|--------|
| **Session / mobile token** | DistantRace-App, eingeloggtes Web | Benutzerbezogene Lese-/Schreibrechte |
| **Org-Token** (`client_credentials`) | Whitelabel-Portal-Backend | Öffentliche Listen, Beitrittscode-Validierung/-Einlösung, Hero-Bilder |
| **User OAuth** (Autorisierungscode + Aktualisierung) | Whitelabel SPA nach Anmeldung | Beitritt, Workouts, Profil, Checkout |

Whitelabel-Integrationen verwenden zwei Arten von Anmeldedaten:

| Anmeldedaten | Verwendung |
|--------------|------------|
| **Org-Token** (langlebiger Berechtigungsträger) | Öffentliche Veranstaltungs-/Challenge-Listen, Hero-Bilder, Beitrittscode-Validierung, E-Mail-Token-Einlösung |
| **User OAuth-Client** (Autorisierungscode) | Teilnehmeranmeldung, Beitritt zu Veranstaltungen, Workouts, Profil, Checkout |

Das Org-Token wird vom Eigentümer der OAuth-Anwendung abgeleitet — jeder Whitelabel-API-Aufruf ist implizit einem Verein zugeordnet.

Konten-Endpunkte umfassen Login-QR, soziale Anmeldung, Profil (`/api/v1/account/me/`) und Geräteanmeldung.

Siehe [Whitelabel- und Unternehmens-Setup](../running-events/whitelabel-and-enterprise-setup.md) für das vollständige Teilnehmerportal-Modell.

### Whitelabel-Beitrittscode-Flows

| Endpunkt | Methode | Zweck |
|----------|---------|-------|
| `event/joincode/{code}/validate/` | GET | Überprüft, ob ein Code für Ihre Organisation aktiv ist; gibt öffentliche Veranstaltungsdaten zurück (keine Teilnehmer-PII) |
| `event/joincode/redeem-email-token/` | POST | Verbraucht ein Magic-Link-Token aus einer Einladungsemail; gibt OAuth-Tokens zurück und kann automatisch in eine Challenge eintragen |
| `event/joincode/` | POST | Erstellt einen Beitrittscode und sendet eine Einladungsemail (nur Admin-Benutzertoken — nicht das öffentliche Org-Token) |

Die Einlösung von Magic-Links verwendet das Org-Token plus ein einmaliges `token` im POST-Body. Der Server kann einen Benutzer aus den Vorabfüllungsdaten des Beitrittscodes erstellen, Zugriffs-/Aktualisierungstokens ausstellen und die automatische Anmeldung aufrufen, wenn der Code an eine Challenge gebunden ist.

### Hero-Bilder (nur Whitelabel)

`GET orgs/hero-images/?language=<code>` — aktive Karussellbilder für die Organisation des Tokens. Erfordert `is_whitelabel` beim Verein. Der optionale Sprachfilter gibt lokalspezifische Bilder plus sprachneutrale Fallbacks zurück.

## Hauptressourcengruppen

| Präfix | Ressourcen |
|--------|------------|
| `event/` | Veranstaltungen, Beitrittscodes, Beiträge |
| `gamification/` | Challenges, Herausforderer, Team-Challenges, Ziele, tägliche Statistiken |
| `races/` | Wettkämpfe, Teilnehmer (Rennfahrer), Ergebnisse |
| `shop/` | Warenkörbe, Warenkorbelemente, Produkte, Premium-Level |
| `users/` | Benutzer, Teilnehmer, Push-Geräte |
| `workouts/` | Aktivitäten, Upload, Sport-/Art-Metadaten |
| `orgs/` | Organisationen, Hero-Bilder (Whitelabel) |
| `finances/` | Zahlungskanäle, Preishelfer |

## Häufige Integrationsaufgaben

| Aufgabe | Typische Endpunkte |
|---------|--------------------|
| Veröffentliche Veranstaltungen auflisten | `event/event/` |
| Teilnehmer registrieren | `races/registration/entrant/` |
| Aktivitäten synchronisieren | `workouts/` oder `workouts/upload/` |
| Ergebnisse lesen | `races/result/` |
| Mobile tägliche Schritte | `gamification/dailystat/` |

## Unternehmens-SSO

SAML-Endpunkte (Plattform-Authentifizierungs-Host):

| Pfad | Zweck |
|------|-------|
| `/saml2/discovery/` | Arbeits-E-Mail eingeben → zum richtigen IdP nach Domain weiterleiten |
| `/saml2/login/` | SAML-Authentifizierung starten (optionale `idp` und `next` Abfrageparameter) |
| `/saml2/acs/` | Assertion Consumer (IdP-Callback) |
| `/saml2/metadata/` | Dienstanbieter-Metadaten für IdP-Konfiguration |

Wenn mehrere Identitätsanbieter existieren, ordnet die Discovery die E-Mail-**Domain** einem IdP zu, bevor sie zur Anmeldung weiterleitet. Bei einem einzigen IdP überspringt die Discovery direkt zu `/saml2/login/`.

Teilnehmer- und Mitarbeiterflüsse: [Unternehmens-SAML und Whitelabel-Anmeldung](../joining-events/enterprise-saml-and-whitelabel-login.md).

## Datenexport-Alternative

Für einmalige Tabellenkalkulationen ohne Programmierung verwenden Sie Manager-**Exporte** — [Organisator-Dokumente](organizer-documents.md), [Ergebnisse-Daten exportieren](../results/exporting-results-data.md), [Jahreseinkommen exportieren](../finance-module/yearly-income-export.md).

## Verwandte Themen

- [Whitelabel- und Unternehmens-Setup](../running-events/whitelabel-and-enterprise-setup.md)
- [Wie man Daten von DistantRace exportiert](how-to-export-data-from-distantrace.md)
- [Integrationen](../integrations/introduction-to-integrations.md)