White-Label-API

Wenn du einen White-Label-Reseller-Workspace betreibst, kannst du deine eigenen Endkunden mit der White-Label-API programmatisch verwalten statt über das Dashboard – baue eine eigene Admin-Konsole, automatisiere das Onboarding, betreibe eigene Auth-Flows auf deiner eigenen Domain oder verknüpfe Guthaben-Aufladungen mit deinem Abrechnungssystem.

Jeder Endpunkt auf dieser Seite erfordert API Access sowie einen API-Schlüssel aus deinem White-Label-Workspace mit dem Scope platform:read oder platform:write und eine Owner- oder Admin-Rolle. Ergebnisse sind immer auf deine eigenen Kunden-Workspaces begrenzt. Ein für einen Kunden ausgestellter Schlüssel kann die REST-API nur verwenden, solange auch dessen Workspace API Access hat; das Ausstellen oder Widerrufen eines Schlüssels vergibt diese Funktion nicht.

Plattform-Nutzer auflisten

GET /api/v1/platform/users listet deine Kunden, neueste zuerst. Paginiere mit limit / offset (siehe Pagination) und suche per Name oder E-Mail mit q.

curl "https://your-domain.example/api/v1/platform/users?limit=20&q=jane" \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Plattform-Nutzer registrieren

POST /api/v1/platform/users legt in deinem Auftrag ein neues Kundenkonto samt Workspace an. Zwei Modi:

invite (Standard) – kein Passwort nötig. Das Konto wird ohne Zugangsdaten angelegt; kombiniere es mit einem Login- oder Token-Aufruf weiter unten, um den Kunden (oder dein eigenes Frontend) tatsächlich hineinzubekommen.
password – du legst direkt ein initiales Passwort (mind. 8 Zeichen) für den Kunden fest.

curl https://your-domain.example/api/v1/platform/users \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@customer.example", "mode": "invite"}'

Eine bereits irgendwo auf der Plattform registrierte E-Mail scheitert mit 409 – die Meldung verrät nie, ob dieses Konto innerhalb oder außerhalb deines eigenen Scopes liegt. Die Registrierungsantwort enthält welcome_credit mit status, requested_credits und granted_credits. Damit kann dein Onboarding anzeigen, ob die einmaligen Willkommens-Credits vergeben wurden oder später manuell übertragen werden müssen.

Willkommens-Credits konfigurieren

GET /api/v1/platform/welcome-credits liefert den einmaligen Betrag, den Status kostenloser Konten und automatischer Vergaben, dein aktuelles Wallet-Guthaben und die geschätzte Anzahl derzeit finanzierbarer Neukunden. Mit PATCH änderst du den Betrag für zukünftige Kunden; 800 Credits ist der empfohlene Startwert, 0 deaktiviert automatische Vergaben.

curl https://your-domain.example/api/v1/platform/welcome-credits \
  -X PATCH \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"welcome_credits": 800}'

Du kannst die Einstellung auch speichern, wenn sie dein aktuelles Wallet-Guthaben übersteigt. Kann das Wallet die vollständige Vergabe nicht decken, funktioniert die Registrierung mit 0 Willkommens-Credits weiter. Sie wird nicht automatisch nachgeholt; nutze nach dem Aufladen die Guthabenübertragung. Bestehende Kunden erhalten keine rückwirkenden Credits und spätere Änderungen gelten nur für zukünftige Kunden.

Plattform-Nutzer einloggen

POST /api/v1/platform/users/login authentifiziert einen Kunden mit dessen E-Mail und Passwort und stellt bei Erfolg ein Zugriffstoken aus. Damit kannst du ein eigenes Login-Formular auf deiner White-Label-Plattform bauen. Fehlgeschlagene Anmeldungen liefern dieselbe allgemeine 401-Antwort und verraten nicht, ob ein Konto existiert.

curl https://your-domain.example/api/v1/platform/users/login \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@customer.example", "password": "correct horse battery staple"}'

Dies ist die einzige White-Label-API-Operation ohne MCP-Pendant – Zugangsdaten sollten nie über einen MCP-Tool-Aufruf laufen.

Nutzer-Token erstellen

POST /api/v1/platform/users/{user_id}/token stellt für einen Kunden einen API-Schlüssel aus, ohne dessen Passwort zu benötigen – geeignet für ein Dashboard, einen Onboarding-Ablauf oder eine autorisierte Automatisierung im Auftrag des Kunden.

curl https://your-domain.example/api/v1/platform/users/USER_ID/token \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "Onboarding token", "expires_in_days": 90}'

Der Klartext-Schlüssel wird genau einmal zurückgegeben – speichere ihn sofort, er lässt sich nicht erneut abrufen. Er gehört dem Kunden, nicht dir: ein weggelassenes scopes gewährt vollen Zugriff für diesen Kunden, nicht nur die Scopes, die dein eigenes Operator-Credential zufällig hat.

Plattform-Nutzer ausloggen

POST /api/v1/platform/users/{user_id}/logout widerruft die aktiven API-Schlüssel und OAuth-Tokens des Kunden in deinem Kundenbereich. Nutze den Endpunkt, um nach einer Kompromittierung oder am Ende einer Kundenbeziehung eine Abmeldung zu erzwingen. Wiederholte Aufrufe sind sicher.

curl https://your-domain.example/api/v1/platform/users/USER_ID/logout \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Guthaben übertragen

POST /api/v1/platform/users/{user_id}/balance verschiebt Credits zwischen dem Guthaben deines Workspace und dem eines Kunden:

Positives credits – vergibt Credits aus deinem Wallet an den Kunden (der Standardweg, um ein Kundenkonto auszustatten).
Negatives credits – holt Credits vom Kunden zurück in dein Wallet.

Beide Richtungen erfordern, dass das Quell-Wallet den Betrag deckt – ein Wallet-Guthaben geht nie unter null, und ein Rückhol-Versuch, der das Kundenguthaben übersteigt, scheitert komplett statt teilweise angewendet zu werden.

curl https://your-domain.example/api/v1/platform/users/USER_ID/balance \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"credits": 50, "note": "Onboarding credit"}'

API-Schlüssel verwalten

Jeder Workspace – auch Kunden-Workspaces aus dieser API – kann seine eigenen API-Schlüssel über /api/v1/api-keys oder Settings → API Keys im Dashboard verwalten. Ein nutzergebundenes Credential kann außerdem direkt über /api/v1/workspaces/{workspace_id}/api-keys einen Key für einen anderen Workspace derselben Brand erstellen, wenn der Nutzer dort aktuell Owner oder Admin ist. Dieser verschachtelte Endpoint ist eine allgemeine Multi-Workspace-Funktion und benötigt keinen White-Label-Zugang.

curl https://your-domain.example/api/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "CRM integration", "scopes": ["calls:read", "leads:write"]}'

Ein Schlüssel kann keinen anderen Schlüssel mit weiterreichenden Rechten erzeugen: scopes eines neuen Schlüssels müssen eine Teilmenge der Scopes des aufrufenden Schlüssels sein. GET /api/v1/api-keys listet Schlüssel ohne ihre Secrets; DELETE /api/v1/api-keys/{id} widerruft einen Schlüssel.

MCP

Alles oben ist auch als MCP-Tools verfügbar, gruppiert im Toolset platform (dazu list_api_keys / create_api_key / revoke_api_key im Toolset settings). Verbinde dich mit dem Toolset-Selektor:

https://your-domain.example/mcp?toolsets=platform

Tool	Entspricht
`list_platform_users`	`GET /api/v1/platform/users`
`get_platform_user`	`GET /api/v1/platform/users/{user_id}`
`register_platform_user`	`POST /api/v1/platform/users`
`get_platform_welcome_credit_settings`	`GET /api/v1/platform/welcome-credits`
`update_platform_welcome_credit_settings`	`PATCH /api/v1/platform/welcome-credits`
`create_platform_user_token`	`POST /api/v1/platform/users/{user_id}/token`
`logout_platform_user`	`POST /api/v1/platform/users/{user_id}/logout`
`transfer_platform_credits`	`POST /api/v1/platform/users/{user_id}/balance`

Ein login_platform_user-Tool gibt es nicht – der Login bleibt aus dem oben genannten Grund REST-only. Die MCP-Tools akzeptieren zur Identifikation des Ziel-Kunden entweder eine user_id oder eine email; REST nimmt user_id immer aus dem URL-Pfad.

White-Label-Verwaltung

Abrechnung

API & MCP

White-Label-API

Plattform-Nutzer auflisten

Plattform-Nutzer registrieren

Willkommens-Credits konfigurieren

Plattform-Nutzer einloggen

Nutzer-Token erstellen

Plattform-Nutzer ausloggen

Guthaben übertragen

API-Schlüssel verwalten

MCP

​Plattform-Nutzer auflisten

​Plattform-Nutzer registrieren

​Willkommens-Credits konfigurieren

​Plattform-Nutzer einloggen

​Nutzer-Token erstellen

​Plattform-Nutzer ausloggen

​Guthaben übertragen

​API-Schlüssel verwalten

​MCP

Plattform-Nutzer auflisten

Plattform-Nutzer registrieren

Willkommens-Credits konfigurieren

Plattform-Nutzer einloggen

Nutzer-Token erstellen

Plattform-Nutzer ausloggen

Guthaben übertragen

API-Schlüssel verwalten

MCP