API de marca blanca

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.

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.

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) y busca por nombre o correo con q.

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.

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.

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.

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

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.

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.

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.

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.

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.

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:

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.

Administración de marca blanca

Facturación

API y MCP

API de marca blanca

Obtener usuarios de la plataforma

Registrar un usuario de la plataforma

Configurar los créditos de bienvenida

Iniciar sesión de un usuario de la plataforma

Crear un token de usuario

Cerrar sesión de un usuario de la plataforma

Transferir saldo

Gestionar claves de API

MCP

​Obtener usuarios de la plataforma

​Registrar un usuario de la plataforma

​Configurar los créditos de bienvenida

​Iniciar sesión de un usuario de la plataforma

​Crear un token de usuario

​Cerrar sesión de un usuario de la plataforma

​Transferir saldo

​Gestionar claves de API

​MCP

Obtener usuarios de la plataforma

Registrar un usuario de la plataforma

Configurar los créditos de bienvenida

Iniciar sesión de un usuario de la plataforma

Crear un token de usuario

Cerrar sesión de un usuario de la plataforma

Transferir saldo

Gestionar claves de API

MCP