> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/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 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 einen API-Schlüssel aus deinem White-Label-Workspace mit den Scopes `platform:read` / `platform:write` sowie eine live geprüfte Owner/Admin-Mitgliedschaft in diesem Workspace. Platform-Admins, die aus ihrem eigenen Root-Workspace agieren, bekommen dieselben Endpunkte automatisch – skopiert auf direkte Plattform-Kunden statt auf die eines Resellers – nie auf die Kunden eines anderen Resellers.
</Note>

## Plattform-Nutzer auflisten

`GET /platform/users` listet die Kunden in deinem Scope, 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 /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.

## Plattform-Nutzer einloggen

`POST /platform/users/login` authentifiziert einen Kunden mit dessen eigener E-Mail und Passwort und stellt bei Erfolg ein Zugriffstoken aus – nutze das, um ein eigenes Login-Formular bzw. einen eigenen Auth-Flow auf deiner White-Label-Plattform zu bauen, statt Kunden zur gehosteten Login-Seite zu schicken. Der Login ist pro IP + E-Mail rate-limitiert, und jeder Fehlschlag – unbekannte E-Mail, falsches Passwort, eine E-Mail außerhalb deines Scopes – liefert exakt dieselbe generische `401`-Meldung, sodass ein Aufrufer aus der Antwort nie ableiten kann, welche Konten existieren.

```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 /platform/users/{user_id}/token` stellt für einen Kunden einen API-Schlüssel aus, ganz ohne dessen Passwort – die richtige Wahl für ein Dashboard, das du baust, eine Onboarding-E-Mail-Sequenz oder jeden automatisierten Workflow 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 /platform/users/{user_id}/logout` widerruft jeden aktiven API-Schlüssel und jedes OAuth-Token, das der Kunde über die Workspace(s) in deinem Scope hält – der Weg, um ein Ausloggen zu erzwingen, etwa nachdem ein Konto kompromittiert wurde oder deine Beziehung zu diesem Kunden endet. Es ist idempotent: Ein bereits ausgeloggter Kunde liefert einfach Zähler mit Wert 0.

```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 /platform/users/{user_id}/balance` verschiebt vorzeichenbehaftete Credits zwischen deinem eigenen Workspace-Wallet 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 die Kunden-Workspaces, die du über diese API bereitstellst – kann seine eigenen API-Schlüssel selbst verwalten, unter `/api-keys`, denselben Endpunkten, die **Einstellungen → API-Schlüssel** im Dashboard antreiben.

```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 nie einen anderen Schlüssel mit weiterreichenden Rechten erzeugen als er selbst hat: `scopes` eines neuen Schlüssels müssen eine Teilmenge der Scopes des aufrufenden Credentials sein (ein Credential mit uneingeschränktem Zugriff darf jeden Scope vergeben; ein weggelassenes `scopes` übernimmt die eigenen Scopes des Aufrufers). `GET /api-keys` listet die Schlüssel eines Workspace, ohne je das Secret preiszugeben; `DELETE /api-keys/{id}` widerruft einen Schlüssel und ist idempotent.

## 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 /platform/users`                    |
| `get_platform_user`          | `GET /platform/users/{user_id}`          |
| `register_platform_user`     | `POST /platform/users`                   |
| `create_platform_user_token` | `POST /platform/users/{user_id}/token`   |
| `logout_platform_user`       | `POST /platform/users/{user_id}/logout`  |
| `transfer_platform_credits`  | `POST /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.