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

> Manage your reseller platform's customers programmatically — list, register, mint tokens, log in, log out, and transfer credits

If you run a [white-label reseller workspace](/admin/tenants-and-whitelabel), the White Label API lets you manage your own end-customers programmatically instead of through the dashboard — build your own admin console, automate onboarding, run custom auth flows on your own domain, or wire credit top-ups into your billing system.

<Note>
  Every endpoint on this page requires API Access plus an API key created in your white-label workspace with the `platform:read` or `platform:write` scope and an owner or admin role. Results are always limited to your own customer workspaces. A key issued for a customer can use the REST API only while that customer workspace also has API Access; issuing or revoking a key does not grant the capability.
</Note>

## Get platform users

`GET /api/v1/platform/users` lists your customers, newest first. Paginate with `limit` / `offset` (see [pagination](/api-reference/introduction#pagination)) and search by name or email with `q`.

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

## Register a platform user

`POST /api/v1/platform/users` creates a new customer account and workspace on your behalf. Two modes:

* **`invite` (default)** — no password required. The account is created without credentials; pair it with a login or token call below to actually get the customer (or your own frontend) into it.
* **`password`** — you choose an initial password (8+ characters) for the customer up front.

```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"}'
```

An email that's already registered anywhere on the platform fails with `409` — the message never reveals whether that account is inside or outside your own scope.

The registration response includes `welcome_credit` with `status`, `requested_credits`, and `granted_credits`. This lets your onboarding UI show whether the one-time welcome credits were granted or need a later manual transfer.

## Configure welcome credits

`GET /api/v1/platform/welcome-credits` returns the configured one-time amount, whether free accounts and automatic grants are active, your current wallet balance, and the estimated number of new customers you can currently fund. `PATCH` updates the amount for future customers; 800 credits is the recommended starting point, and 0 disables automatic grants.

```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}'
```

Saving is allowed even when the amount is above your current wallet balance. If the wallet cannot cover a new customer's full grant, signup still succeeds with 0 welcome credits. It is not caught up automatically; use the balance transfer action when your wallet is funded. Existing customers are never credited retroactively, and later setting changes apply only to future customers.

## Log in a platform user

`POST /api/v1/platform/users/login` authenticates a customer with their own email and password and returns an access token on success. Use it to build a login form on your white-label platform instead of sending customers to the hosted login page. Failed sign-ins return the same generic `401` response and do not reveal whether an account exists.

```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>
  This is the one White Label API operation with no MCP equivalent — credentials should never travel through an MCP tool call.
</Warning>

## Create a user token

`POST /api/v1/platform/users/{user_id}/token` creates an API key for a customer without needing their password — useful for a dashboard, onboarding flow, or approved automation acting on the customer's behalf.

```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}'
```

The plaintext key is returned exactly once — store it immediately, it cannot be retrieved again. It belongs to the customer, not you: an omitted `scopes` grants full access for that customer, not just the scopes your own operator credential happens to have.

## Log out a platform user

`POST /api/v1/platform/users/{user_id}/logout` revokes the customer's active API keys and OAuth tokens in your customer scope. Use it to force a sign-out after an account is compromised or your relationship with that customer ends. Repeating the request is safe.

```bash theme={null}
curl https://your-domain.example/api/v1/platform/users/USER_ID/logout \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"
```

## Transfer balance

`POST /api/v1/platform/users/{user_id}/balance` moves credits between your workspace balance and a customer's:

* **Positive `credits`** — grants credits from your wallet to the customer (the standard way to provision a customer account).
* **Negative `credits`** — reclaims credits back from the customer into your wallet.

Either direction requires the source wallet to cover the amount — a wallet balance never goes below zero, and an attempted reclaim that exceeds the customer's balance fails outright instead of partially applying.

```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"}'
```

## Manage API keys

Every workspace — including customer workspaces created through this API — can manage its own API keys through `/api/v1/api-keys` or **Settings → API Keys** in the dashboard. A user-owned credential can also mint a key directly for another same-brand workspace where that user is currently an owner or admin by calling `/api/v1/workspaces/{workspace_id}/api-keys`. That nested endpoint is a general multi-workspace capability and does not require white-label access.

```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"]}'
```

A key can never create another key with broader access than itself: `scopes` on a new key must be a subset of the calling credential's scopes. `GET /api/v1/api-keys` lists a workspace's keys without exposing their secrets; `DELETE /api/v1/api-keys/{id}` revokes one.

## MCP

Everything above is also available as MCP tools, grouped in the **`platform`** toolset (plus `list_api_keys` / `create_api_key` / `revoke_api_key` in the `settings` toolset). Connect with the toolset selector:

```text theme={null}
https://your-domain.example/mcp?toolsets=platform
```

| Tool                                      | Maps to                                         |
| ----------------------------------------- | ----------------------------------------------- |
| `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` |

There's no `login_platform_user` tool — logging in stays REST-only, for the reason above. The MCP tools accept either a `user_id` or an `email` to identify the target customer; REST always takes `user_id` from the URL path.