---
title: Overzicht van de openbare API
description: REST API-eindpunten voor mobiele apps, integraties en whitelabelplatforms
order: 5
source_hash: bbd272c97e8f
slug: overzicht-van-de-openbare-api
---

# Overzicht van de openbare API

DistantRace biedt een **REST API** (`/api/v1/`) die wordt gebruikt door de mobiele app, partnerintegraties en whitelabelplatforms. Dit is een overzicht op hoog niveau — geen volledige OpenAPI-referentie.

::: warning Integratie-ondersteuning
API-toegang voor ontwikkeling door derden wordt doorgaans geregeld met ondersteuning van DistantRace. Authenticatie en snelheidslimieten zijn van toepassing.
:::

## Basis-URL

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

## Authenticatie

| Toekenning / token | Typische oproeper | Bereik |
|---------------|----------------|-------|
| **Sessie / mobiele token** | DistantRace-app, ingelogde web | Gebruikersgericht lezen/schrijven |
| **Org token** (`client_credentials`) | Whitelabel portal backend | Openbare lijsten, join-code valideren/inwisselen, hero-afbeeldingen |
| **User OAuth** (autorisatiecode + vernieuwen) | Whitelabel SPA na inloggen | Deelnemen, trainingen, profiel, afrekenen |

Whitelabelintegraties gebruiken twee soorten referenties:

| Referentie | Gebruik |
|------------|-----|
| **Org token** (langdurige drager) | Openbare evenement/uitdaging lijsten, hero-afbeeldingen, join-code validatie, e-mailtoken inwisseling |
| **User OAuth client** (autorisatiecode) | Deelnemer inloggen, deelnemen aan evenementen, trainingen, profiel, afrekenen |

Het org token wordt afgeleid van de eigenaar van de OAuth-applicatie — elke whitelabel API-oproep is impliciet gericht op één club.

Account-eindpunten omvatten login QR, sociale login, profiel (`/api/v1/account/me/`), en apparaatregistratie.

Zie [Whitelabel en enterprise setup](../running-events/whitelabel-and-enterprise-setup.md) voor het volledige deelnemersportaalmodel.

### Whitelabel join-code stromen

| Eindpunt | Methode | Doel |
|----------|--------|---------|
| `event/joincode/{code}/validate/` | GET | Controleer of een code actief is voor uw organisatie; retourneert openbare evenementgegevens (geen persoonlijke gegevens van deelnemers) |
| `event/joincode/redeem-email-token/` | POST | Gebruik een magic-link token uit een uitnodigingse-mail; retourneert OAuth-tokens en kan automatisch inschrijven voor een uitdaging |
| `event/joincode/` | POST | Maak een join-code en stuur een uitnodigingse-mail (alleen admin-gebruikertoken — niet het openbare org token) |

Magic-link inwisseling gebruikt het org token plus een eenmalige `token` in de POST-body. De server kan een gebruiker maken van join-code vooraf ingevulde gegevens, toegang/vernieuw tokens uitgeven, en automatisch inschrijven wanneer de code aan een uitdaging is gekoppeld.

### Hero-afbeeldingen (alleen whitelabel)

`GET orgs/hero-images/?language=<code>` — actieve carrouselafbeeldingen voor de organisatie van het token. Vereist `is_whitelabel` op de club. Optioneel taalfilter retourneert taalspecifieke afbeeldingen plus taalneutrale back-ups.

## Belangrijkste resourcegroepen

| Prefix | Resources |
|--------|-----------|
| `event/` | Evenementen, join-codes, berichten |
| `gamification/` | Uitdagingen, uitdagers, teamuitdagingen, doelen, dagelijkse statistieken |
| `races/` | Wedstrijden, deelnemers (racers), resultaten |
| `shop/` | Winkelwagens, winkelwagenitems, producten, premium niveaus |
| `users/` | Gebruikers, deelnemers, push-apparaten |
| `workouts/` | Activiteiten, uploaden, sport/type metadata |
| `orgs/` | Organisaties, hero-afbeeldingen (whitelabel) |
| `finances/` | Betalingskanalen, prijshelpers |

## Veelvoorkomende integratietaken

| Taak | Typische eindpunten |
|------|-------------------|
| Gepubliceerde evenementenlijst | `event/event/` |
| Deelnemer registreren | `races/registration/entrant/` |
| Activiteiten synchroniseren | `workouts/` of `workouts/upload/` |
| Resultaten lezen | `races/result/` |
| Mobiele dagelijkse stappen | `gamification/dailystat/` |

## Enterprise SSO

SAML-eindpunten (platformauthenticatiehost):

| Pad | Doel |
|------|---------|
| `/saml2/discovery/` | Voer werk-e-mail in → routeer naar de juiste IdP op basis van domein |
| `/saml2/login/` | Start SAML-authenticatie (optionele `idp` en `next` query parameters) |
| `/saml2/acs/` | Assertion consumer (IdP callback) |
| `/saml2/metadata/` | Serviceprovider metadata voor IdP-configuratie |

Wanneer er meerdere identiteitsproviders zijn, stemt discovery het e-mail **domein** af op een IdP voordat er naar login wordt omgeleid. Met een enkele IdP slaat discovery direct naar `/saml2/login/` over.

Deelnemer- en personeelstromen: [Enterprise SAML en whitelabel login](../joining-events/enterprise-saml-and-whitelabel-login.md).

## Alternatief voor data-export

Voor eenmalige spreadsheets zonder codering, gebruik manager **exports** — [Organisator documenten](organizer-documents.md), [Resultaatgegevens exporteren](../results/exporting-results-data.md), [Jaarlijkse inkomensexport](../finance-module/yearly-income-export.md).

## Gerelateerd

- [Whitelabel en enterprise setup](../running-events/whitelabel-and-enterprise-setup.md)
- [Hoe gegevens exporteren van DistantRace](how-to-export-data-from-distantrace.md)
- [Integraties](../integrations/introduction-to-integrations.md)