Autenticación

Esta página describe cómo se establece y se comprueba una sesión de T-Suite, y qué pasos de verificación adicionales protegen las acciones sensibles. Explica el comportamiento; no es un contrato para una integración. Las integraciones se acuerdan primero con Libertum — véase Desarrolladores.

Flujo de inicio de sesión

Cada inicio de sesión tiene al menos dos pasos, y un tercero cuando la autenticación de dos factores está activada:

1. Correo y contraseña. El usuario envía sus credenciales. Si son correctas, la plataforma todavía no emite una sesión — envía un código de un solo uso al correo del usuario.
2. Código por correo. El usuario envía el código. El código por correo se exige en cada inicio de sesión, no solo en el primero.
3. Código del autenticador (si el 2FA está activado). Si la cuenta tiene activada la autenticación de dos factores, el paso del correo devuelve un token intermedio de corta duración en lugar de una sesión. El usuario envía entonces un código de 6 dígitos de su app autenticadora — o uno de sus códigos de respaldo — junto con ese token.

Solo después del último paso la plataforma devuelve un token de acceso.

Sesiones y tokens de acceso

• Token bearer. Las peticiones autenticadas llevan el token de acceso en la cabecera Authorization como Bearer seguido del token.
• Una sola sesión activa por cuenta. La plataforma fija en el servidor el token de acceso vigente de cada cuenta. Iniciar sesión de nuevo — en otro dispositivo o navegador — reemplaza el token fijado, y el token anterior deja de funcionar. Cerrar sesión lo elimina.
• Vida útil fija, sin endpoint de renovación. Los tokens de acceso caducan tras un periodo fijo. No existe una llamada para renovar el token; cuando caduca, el usuario vuelve a iniciar sesión.
• Cuentas bloqueadas. Si un administrador desactiva una cuenta, su siguiente petición se rechaza y la sesión se elimina.

Respuestas habituales cuando una sesión no se puede usar:

Estado	Significado
401	Sin token, token inválido o caducado, o un token reemplazado por un inicio de sesión más reciente
403	La cuenta tiene 2FA activado pero no se completó el paso del autenticador, o la cuenta está bloqueada
503	El almacén de sesiones no está disponible temporalmente — se debe reintentar más tarde en lugar de cerrar la sesión del usuario

Autenticación de dos factores

Los usuarios pueden activar la autenticación de dos factores desde la configuración de su cuenta:

• App autenticadora (TOTP). El usuario escanea un código QR con cualquier app autenticadora estándar y confirma con un primer código.
• Códigos de respaldo. Al activar el 2FA, el usuario recibe 8 códigos de respaldo de un solo uso. Cada código funciona una vez; la plataforma solo guarda su hash, muestra cuántos códigos sin usar quedan y permite generar un juego nuevo.
• Un código de respaldo se acepta en cualquier lugar donde se acepta un código del autenticador — al iniciar sesión y en la verificación reforzada.

Verificación reforzada para acciones sensibles

Algunas acciones necesitan una prueba de identidad reciente incluso dentro de una sesión válida:

Acción	Verificación
Retiro de la Custodian Wallet	Un código por correo (6 dígitos, válido durante 10 minutos), o un código del autenticador, o uno de los códigos de respaldo
Firma de un acuerdo de inversión	Se solicita y se confirma un código de un solo uso antes de registrar la firma
Firma de documentos de Structuring	Un código de un solo uso confirma la firma

Las solicitudes de códigos de verificación para retiros tienen límite de tasa.

Los retiros tienen controles adicionales además del código — una dirección guardada con al menos 24 horas de antigüedad, límites por transacción y diarios, y aprobación de Libertum por encima de un umbral. Véase la página de Custodian Wallet.

La puerta de onboarding

Una sesión válida no basta, por sí sola, para operaciones financieras. La mayoría de las rutas de producto (órdenes, ofertas, transferencias, la Custodian Wallet, Distribution Hub, Structuring y otras) comprueban además que el usuario haya terminado el onboarding:

1. Una suscripción activa — el plan gratuito de Inversionista cuenta.
2. Verificación de identidad aprobada — KYC para personas, KYB para instituciones (ambas a través de SumSub).
3. Aprobación manual de la cuenta, cuando un despliegue la exige.

Si falta un paso, la API responde 403 con requiresOnboarding: true y un valor missingStep (subscription, kyc, kyb o approval), para que un cliente pueda llevar al usuario a la pantalla correcta sin interpretar el texto del mensaje.

Las rutas de perfil, KYC y configuración siguen accesibles durante el onboarding, para que el usuario pueda completarlo.

Llamadas entre servidores

Las herramientas administrativas propias de Libertum no llaman a la API del marketplace con una sesión de usuario. Sus peticiones viajan entre servidores a través de un proxy de administración, y cada petición se firma con un HMAC que la API del marketplace verifica antes de actuar. Estas rutas administrativas no están disponibles para clientes ni integradores.

Las llamadas entrantes de proveedores como SumSub y Stripe también se verifican por firma antes de procesarse.

Resolución del tenant whitelabel

La misma API sirve a la app propia de Libertum y al dominio propio de cada tenant whitelabel. La API determina a qué tenant pertenece una petición a partir del dominio desde el que se sirve la app, y lo usa para aplicar el branding del tenant, el alcance de su marketplace y su configuración.

Las peticiones desde el navegador solo se aceptan desde los orígenes propios de Libertum y desde dominios de tenant verificados. Un dominio propio que no ha completado la verificación de dominio no puede llamar a la API desde un navegador.

API keys (solo Stablecoin Studio)

El único lugar donde hoy se usa una credencial de máquina es la API para desarrolladores de Stablecoin Studio: un emisor crea y revoca API keys desde la página Developer de Stablecoin Studio, y cada key solo puede leer los datos de ese emisor. Todo el resto del acceso a la API usa una sesión de usuario como se describe arriba. Véase Panorama de la API.