> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# White-Label-API

> Verwalte die Kunden deiner Reseller-Plattform programmatisch – auflisten, registrieren, Tokens ausstellen, einloggen, ausloggen und Guthaben übertragen

Wenn du einen [White-Label-Reseller-Workspace](/de/admin/tenants-and-whitelabel) 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.

<Note>
  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.
</Note>

## Plattform-Nutzer auflisten

`GET /api/v1/platform/users` listet deine Kunden, neueste zuerst. Paginiere mit `limit` / `offset` (siehe [Pagination](/de/api-reference/introduction#pagination)) und suche per Name oder E-Mail mit `q`.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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"}'
```

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

## 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:

```text theme={null}
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.