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

# API de marca blanca

> Gestiona mediante programación a los clientes de tu plataforma de revendedor — listar, registrar, generar tokens, iniciar sesión, cerrar sesión y transferir créditos

Si operas un espacio de trabajo de revendedor de marca blanca, la API de marca blanca te permite gestionar a tus propios clientes finales mediante programación en lugar de a través del panel — crea tu propia consola de administración, automatiza la incorporación, ejecuta flujos de autenticación personalizados en tu propio dominio o conecta las recargas de crédito a tu sistema de facturación.

<Note>
  Todos los endpoints de esta página requieren API Access, una clave de API creada en tu espacio de trabajo de marca blanca con el alcance `platform:read` o `platform:write` y un rol de propietario o administrador. Los resultados siempre se limitan a tus propios espacios de trabajo de clientes. Una clave emitida para un cliente solo puede usar la API REST mientras su espacio de trabajo también tenga API Access; emitir o revocar una clave no concede esta función.
</Note>

## Obtener usuarios de la plataforma

`GET /api/v1/platform/users` enumera tus clientes, del más reciente al más antiguo. Pagina con `limit` / `offset` (consulta [paginación](/es/api-reference/introduction#paginación)) y busca por nombre o correo con `q`.

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

## Registrar un usuario de la plataforma

`POST /api/v1/platform/users` crea una cuenta de cliente y un espacio de trabajo nuevos en tu nombre. Dos modos:

* **`invite` (predeterminado)** — no requiere contraseña. La cuenta se crea sin credenciales; combínalo con una llamada de inicio de sesión o de token (más abajo) para que el cliente (o tu propio frontend) pueda acceder realmente.
* **`password`** — eliges de antemano una contraseña inicial (8 o más caracteres) para el cliente.

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

Un correo que ya está registrado en cualquier parte de la plataforma falla con `409` — el mensaje nunca revela si esa cuenta está dentro o fuera de tu propio alcance.

La respuesta del registro incluye `welcome_credit` con `status`, `requested_credits` y `granted_credits`. Esto permite que tu interfaz de incorporación muestre si los créditos de bienvenida (únicos) se concedieron o si necesitan una transferencia manual posterior.

## Configurar los créditos de bienvenida

`GET /api/v1/platform/welcome-credits` devuelve el importe único configurado, si las cuentas gratuitas y las concesiones automáticas están activas, el saldo actual de tu monedero y el número estimado de clientes nuevos que puedes financiar ahora mismo. `PATCH` actualiza el importe para los futuros clientes; 800 créditos es el punto de partida recomendado, y 0 desactiva las concesiones automáticas.

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

Puedes guardar el importe aunque sea superior al saldo actual de tu monedero. Si el monedero no alcanza para cubrir la concesión completa de un cliente nuevo, el registro se completa igualmente con 0 créditos de bienvenida. Esto no se compensa automáticamente después; usa la acción de transferencia de saldo cuando tu monedero tenga fondos. Los clientes existentes nunca reciben créditos con carácter retroactivo, y los cambios posteriores de configuración solo se aplican a los clientes futuros.

## Iniciar sesión de un usuario de la plataforma

`POST /api/v1/platform/users/login` autentica a un cliente con su propio correo y contraseña y, si tiene éxito, devuelve un token de acceso. Úsalo para crear un formulario de inicio de sesión en tu plataforma de marca blanca en lugar de enviar a los clientes a la página de inicio de sesión alojada. Los inicios de sesión fallidos devuelven la misma respuesta genérica `401` y no revelan si la cuenta existe.

```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>
  Esta es la única operación de la API de marca blanca sin equivalente en MCP — las credenciales nunca deben viajar a través de una llamada a una herramienta MCP.
</Warning>

## Crear un token de usuario

`POST /api/v1/platform/users/{user_id}/token` crea una clave de API para un cliente sin necesitar su contraseña — útil para un panel, un flujo de incorporación o una automatización aprobada que actúe en nombre del cliente.

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

La clave en texto plano se devuelve una única vez — guárdala de inmediato, no se puede recuperar después. Pertenece al cliente, no a ti: si omites `scopes`, se concede acceso completo para ese cliente, no solo los alcances que tenga tu propia credencial de operador.

## Cerrar sesión de un usuario de la plataforma

`POST /api/v1/platform/users/{user_id}/logout` revoca las claves de API activas y los tokens OAuth del cliente dentro de tu alcance de cliente. Úsalo para forzar el cierre de sesión después de que una cuenta se vea comprometida o cuando termine tu relación con ese cliente. Repetir la solicitud es seguro.

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

## Transferir saldo

`POST /api/v1/platform/users/{user_id}/balance` mueve créditos entre el saldo de tu espacio de trabajo y el de un cliente:

* **`credits` positivo** — concede créditos de tu monedero al cliente (la forma estándar de aprovisionar la cuenta de un cliente).
* **`credits` negativo** — recupera créditos del cliente de vuelta a tu monedero.

Cualquiera de las dos direcciones requiere que el monedero de origen cubra el importe — un saldo nunca baja de cero, y un intento de recuperación que supere el saldo del cliente falla por completo en lugar de aplicarse parcialmente.

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

## Gestionar claves de API

Cualquier espacio de trabajo — incluidos los espacios de cliente creados mediante esta API — puede gestionar sus propias claves de API a través de `/api/v1/api-keys` o de **Settings → API Keys** en el panel. Una credencial propiedad de un usuario también puede generar una clave directamente para otro espacio de la misma marca en el que ese usuario sea actualmente propietario o administrador, llamando a `/api/v1/workspaces/{workspace_id}/api-keys`. Ese endpoint anidado es una capacidad general multiespacio y no requiere acceso de marca blanca.

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

Una clave nunca puede crear otra clave con más acceso que ella misma: `scopes` en una clave nueva debe ser un subconjunto de los alcances de la credencial que hace la llamada. `GET /api/v1/api-keys` enumera las claves de un espacio de trabajo sin exponer sus secretos; `DELETE /api/v1/api-keys/{id}` revoca una.

## MCP

Todo lo anterior también está disponible como herramientas MCP, agrupadas en el grupo **`platform`** (además de `list_api_keys` / `create_api_key` / `revoke_api_key` en el grupo `settings`). Conéctate con el selector de grupos de herramientas:

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

| Herramienta                               | Equivale a                                      |
| ----------------------------------------- | ----------------------------------------------- |
| `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` |

No existe una herramienta `login_platform_user` — el inicio de sesión se mantiene exclusivamente en REST, por el motivo indicado arriba. Las herramientas MCP aceptan un `user_id` o un `email` para identificar al cliente de destino; REST siempre toma `user_id` de la ruta de la URL.