White-Label-Einbettung

Hol die Einnahmedaten eines Affiliates mit einem Token pro Affiliate ab und zeig sie in deinem eigenen Produkt an.

Mit der Einbettung zeigt eine Marke die Einnahmen jedes Affiliates in ihrem eigenen Produkt an. Du erzeugst ein Token pro Affiliate, rufst damit von deiner eigenen Seite aus die Einnahmedaten des Affiliates ab und stellst die Zahlen in deiner Oberfläche dar. Verfügbar ab Growth.

Was die Funktion macht

Ein Affiliate meldet sich wie gewohnt in deinem Produkt an. Deine Seite ruft mit einem Token pro Affiliate den Daten-Endpunkt für die Einbettung bei Rekomi ab und zeigt die Einnahmen und die letzten Conversions des Affiliates in deiner eigenen Oberfläche an. Der Affiliate muss deine Domain nie verlassen und sich nicht separat bei Rekomi anmelden.

Nur lesend. Der Endpunkt liefert Daten; Aktionen kann der Affiliate darüber nicht ausführen (keine Bewerbung, keine Profiländerung, kein Hochladen von Steuerformularen). Dafür meldet er sich weiterhin in seinem Rekomi-Dashboard für Affiliates an.

Ein Token erzeugen

Zum Erzeugen von Tokens braucht es einen Owner oder Admin des Kontos (oder einen API-Schlüssel mit Lese- und Schreibzugriff) in einem Plan ab Growth. Mitglieder mit der Rolle Manager oder Viewer können keine Tokens erzeugen oder widerrufen.

POST /api/v1/embed/tokens
Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "affiliateId": "b3d7e2a1-4c9f-4e8a-9f21-0a1b2c3d4e5f",
  "allowedOrigins": "https://yourapp.com,https://app.yourapp.com",
  "rotate": false,
  "expiresInHours": 24
}

Pflichtfelder:

affiliateId: der Affiliate (eine UUID), auf den dieses Token beschränkt ist. Er muss Affiliate in einem deiner Programme sein.
allowedOrigins: kommagetrennte Liste der Origins (Schema + Host + Port), die die Einbettung einbinden dürfen. Es gilt exakte Gleichheit; Platzhalter gibt es nicht. Faktisch ein Pflichtfeld: Das Erzeugen klappt auch ohne, aber jeder Datenabruf liefert 403 no_allowed_origins_configured, bis du das Token mit gesetzten Origins rotierst.

Optional:

rotate (Boolean, Standard false): Bei true ersetzt ein neues Token jedes bestehende Token für das Paar (Programm, Affiliate). Bei false und einem bereits vorhandenen Token liefert die Antwort die Metadaten des bestehenden Tokens (ID, erlaubte Origins, Ablauf) mit alreadyExists: true und ohne Klartext-Token; für ein neues Klartext-Token musst du rotate: true setzen.
expiresInHours (Ganzzahl, Standard 24, begrenzt auf [1, 720]): Gültigkeitsdauer in Stunden. Über 30 Tage (720 Stunden) hinaus rotierst du, statt zu verlängern.

Antwort (neues oder rotiertes Token):

{
  "token": "kY3xTq8Zr1Nf6Wb2Jm9Lp4Vc7Hd0Ag",
  "allowedOrigins": "https://yourapp.com,https://app.yourapp.com",
  "expiresAt": "2026-05-12T03:14:25.000Z"
}

Das Token ist eine anonyme, URL-sichere Zufallszeichenfolge aus 24 Bytes ohne Präfix. Das token im Klartext wird GENAU EINMAL zurückgegeben. Speichere es auf deinem Anwendungsserver, bevor du es an den Browser weitergibst; wiederherstellen können wir es nicht. Bei uns wird nur ein Hash gespeichert; der öffentliche Dashboard-Endpunkt hasht das eingehende Token vor dem Vergleich.

Tokens gelten standardmäßig 24 Stunden. Erzeuge neue Tokens, wenn sich der Affiliate anmeldet. Gib keine langlebigen Tokens an den Browser weiter.

Die Daten abrufen und anzeigen

Der Dashboard-Endpunkt liefert JSON, keine HTML-Seite. Ruf ihn von deiner eigenen Seite aus ab (ein Cross-Origin-Abruf sendet den Header Origin, den die Positivliste prüft) und stell die Einnahmen in deinem Produkt dar, im Look der zurückgegebenen Markenfarbe.

const res = await fetch(
  "https://api.rekomi.com/api/embed/public/dashboard?token=kY3xTq8Zr1Nf6Wb2Jm9Lp4Vc7Hd0Ag"
);
const data = await res.json();
// render data.earnedCents, data.recentConversions, etc. in your own UI

Die Antwort enthält schreibgeschützte Einnahmen und die letzten Conversions des Affiliates, für den das Token ausgestellt wurde, dazu deine Markenfarbe und deinen Namen, damit du den Bereich passend gestalten kannst (siehe „Anpassung“ unten). Der Header Origin, den dein Browser beim Cross-Origin-Abruf sendet, muss exakt mit einem der allowedOrigins des Tokens übereinstimmen. Ruf den Endpunkt also von einer Seite auf, die unter einem Origin auf der Positivliste ausgeliefert wird.

Positivliste der Origins

Die Einbettung prüft den Origin streng. Der Header Origin, den der Browser (beim Cross-Origin-Abruf) sendet, muss exakt einem der Einträge in allowedOrigins entsprechen. Verglichen werden:

Schema (https oder http)
Host
Port (ausdrücklich angegeben, wenn er nicht der Standard ist)

Keine Prüfung per StartsWith. Keine Platzhalter für Subdomains. Das ist nötig, weil eine Regel mit StartsWith es https://yourapp.com.evil.example.com erlauben würde, die Prüfung zu umgehen.

Brauchst du mehrere Origins, trag sie alle in die Liste ein. Lieferst du von vielen Subdomains aus, erzeuge Tokens pro Deployment, die nur den jeweils passenden Origin enthalten.

Was die Einbettung zeigt

Der Endpunkt GET /api/embed/public/dashboard?token=... liefert:

Feld	Typ	Beschreibung
`affiliateName`	string\|null	Vollständiger Name des Affiliates (ohne gesetzten Namen die E-Mail-Adresse)
`programName`	string\|null	Das Programm, in dem der Affiliate ist (innerhalb deiner Organisation)
`earnedCents`	integer	Verdiente Provision (Summe von `commissionCents` über freigegebene und ausgezahlte Conversions) aus den letzten Conversions des Affiliates
`paidCents`	integer	Der Teil von `earnedCents`, der schon ausgezahlt wurde
`pendingCents`	integer	`earnedCents - paidCents`
`brandColor`	string	Die Markenfarbe deiner Organisation (ohne Einstellung `#0E7C7B`). Nutze sie, um den Bereich zu gestalten.
`brandName`	string\|null	Der Anzeigename deiner Organisation. Zeig ihn in der Kopfzeile deines Bereichs.
`recentConversions[]`	array	Bis zu 20 der letzten Conversions, die neueste zuerst. Jeder Eintrag: `{ id, amountCents, commissionCents, status, createdAt }`.

Die Summen earnedCents, paidCents und pendingCents werden über die 50 letzten Conversions des Affiliates berechnet, nicht über die gesamte Historie. Bei Affiliates mit hohem Volumen können sie die tatsächlichen Summen also unterschätzen.

Eine realistische JSON-Antwort:

{
  "affiliateName": "Jane Doe",
  "programName": "Default program",
  "earnedCents": 12450,
  "paidCents": 9800,
  "pendingCents": 2650,
  "brandColor": "#0E7C7B",
  "brandName": "Your Brand",
  "recentConversions": [
    {
      "id": "c0nv0001-...",
      "amountCents": 9900,
      "commissionCents": 1980,
      "status": "Approved",
      "createdAt": "2026-05-10T16:00:00Z"
    }
  ]
}

Das ist die vollständige Payload. Keine Steuerformulare, kein Status von Stripe Connect, keine Einstellungen, keine IP-Adressen, keine personenbezogenen Daten über das hinaus, dessen Anzeige der Affiliate zugestimmt hat.

Was die Einbettung NICHT zeigt

Programme anderer Organisationen (auch wenn der Affiliate in mehreren ist)
Status des Steuerformulars (personenbezogene Daten)
Bankdaten aus Stripe Connect (personenbezogene Daten)
Daten anderer Affiliates

Die Einbettung ist streng auf ein Paar (Organisation, Affiliate) beschränkt.

Anpassung

Die Dashboard-Antwort liefert brandColor (aus der Einstellung für die Markenfarbe deiner Organisation unter /dashboard/settings/branding, ohne Einstellung #0E7C7B) und brandName (den Anzeigenamen deiner Organisation). Gestalte deinen Bereich auf deiner Seite mit diesen Werten, passend zum Look deines Produkts.

Textfarbe, Layout und Typografie lassen sich nicht serverseitig anpassen; der Endpunkt liefert nur Daten. Künftige Versionen bekommen beim Erzeugen des Tokens ein JSON zur Anpassung (Spalten ein- und ausblenden, Text der Kopfzeile, eigene CSS-Variablen).

Plan-Voraussetzung

POST /api/v1/embed/tokens ist ab dem Plan Growth verfügbar. Ist deine Organisation im Plan Starter, liefert der Endpunkt HTTP 402 mit { error: "plan_tier_required", required: "Growth", current: "Starter" }.

Sicherheits-Checkliste

Erzeuge Tokens immer serverseitig. Gib den Bearer-API-Schlüssel nie an den Browser weiter.
Setze allowedOrigins immer auf den exakten Produktions-Origin.
Erzeuge pro Sitzung neue Tokens (nutze ein 24-Stunden-Token nicht über viele Sitzungen hinweg).
Prüfe die Authorization der eingehenden Nutzeranfrage, bevor du ein Token erzeugst (nur der tatsächlich angemeldete Affiliate darf ein Token für seine eigenen Daten bekommen).
Ruf den Daten-Endpunkt nur von Seiten auf, die unter einem Origin auf der Positivliste ausgeliefert werden, damit der Browser den Header Origin sendet, den die Positivliste prüft.

Fehlerbehebung

origin_not_allowed: Dein Header Origin passt zu keinem Eintrag in allowedOrigins. Prüfe Schema, Host und Port auf exakte Gleichheit. Ein fehlerhafter Wert für Origin liefert stattdessen origin_invalid.
origin_required: Die Anfrage hat keinen Header Origin gesendet (z. B. curl, Server-zu-Server). Der Dashboard-Endpunkt verlangt Origin, auch wenn allowedOrigins gesetzt ist. Ruf ihn also per Cross-Origin-Abruf aus einer Browser-Seite auf, nicht serverseitig.
token_expired (401): Das expiresAt des Tokens liegt in der Vergangenheit. Erzeuge bei der nächsten Sitzung ein neues.
Erzeugen des Tokens liefert 404: Die affiliateId gehört zu keinem Affiliate in deiner Organisation. Sie muss auf einen deiner Affiliates verweisen.
Leere Antwort oder CORS-Fehler: Sieh in die Konsole deines Browsers. Prüfe, ob du von einer Seite abrufst, deren Origin in den allowedOrigins des Tokens steht, und ob das Token nicht widerrufen wurde (ein unbekanntes oder widerrufenes Token liefert 401).

White-Label-Einbettung

On this page