Login

Autenticacion

Autenticacion y gestion de tokens JWT.

Descripcion

Autentica usuario con username y secret usando Usuario::loginWithApiKey. Genera JWT HS512 con expiracion de 6 horas y refresh token.

Este endpoint no cambia con la incorporacion de API keys de empresa. Las integraciones actuales pueden seguir autenticando exactamente igual que antes.

Endpoint

• Metodo: POST
• Path: /api/auth/login

Headers

• Content-Type: application/json

Proteccion contra intentos automatizados

El endpoint registra los fallos por IP, prefijo de red e identificador normalizado. Los limites de IP/red cortan el spraying con 429 Too Many Requests y un header Retry-After. Los accesos correctos no consumen cuota, por lo que una integracion que autentica correctamente no queda limitada por su frecuencia de login.

Los fallos distribuidos contra un mismo identificador se detectan y alertan, pero no bloquean por si solos una credencial correcta desde otra red. Esto evita que un tercero pueda denegar el acceso de una cuenta conocida.

Las integraciones deben respetar Retry-After, detener reintentos automaticos y evitar ciclos de autenticacion cuando ya disponen de un JWT o refresh token vigente. La respuesta no indica cual de los limites fue alcanzado.

Compatibilidad hacia atras

• POST /api/auth/login sigue funcionando con el flujo legacy actual.
• No se exige API key de empresa a integradores existentes.
• La autenticacion directa por API key de empresa es adicional y aplica solo cuando el request envia X-API-Key o Authorization: Bearer bt_live_... / bt_test_... hacia endpoints protegidos.

Autenticacion directa por API key de empresa

Ademas del login legacy, ahora puedes autenticar requests directamente en la API usando una API key de empresa activa:

• X-API-Key: bt_live_...
• Authorization: Bearer bt_live_...
• X-API-Key: bt_test_...
• Authorization: Bearer bt_test_...

Ejemplo:

curl -X GET '$BASE/api/v1/usuario/empresas' \
  -H 'X-API-Key: bt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Las claves bt_test_... corresponden a workspaces Sandbox y las bt_live_... a workspaces de Produccion. Ambos ambientes son independientes y no comparten datos ni credenciales.

Si no envias una API key de empresa, el sistema continua usando el flujo legacy actual sin cambios.

Rate limiting para API keys

Los requests autenticados por API key pueden tener limites por minuto y por hora definidos por empresa o por clave.

Cuando una API key supera su limite configurado, el endpoint protegido responde:

• HTTP 429 Too Many Requests
• body con code = api_key_rate_limit_exceeded
• headers Retry-After, X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Hour, X-RateLimit-Remaining-Hour

Este comportamiento no cambia el flujo legacy si el request no usa API key.

Cómo obtener el secret

El secret es la contraseña del usuario en el sistema. Para usuarios integradores, existen las siguientes opciones:

Opción 1: Usuario existente

Si ya tienes un usuario creado en el sistema:

• Contacta al administrador del sistema para obtener o resetear la contraseña
• Usa la contraseña actual del usuario

Opción 2: Crear nuevo usuario integrador

Para crear un nuevo usuario con API key:

1. Crear usuario: Via panel de administración o endpoint de registro público
2. Generar API Key: Usa el endpoint POST /api/v1/usuario/{idUsuario}/apikey
3. Usar la API Key como secret: La API Key generada puede usarse como secret en el login

Opción 3: Recuperar contraseña

Si olvidaste la contraseña:

• Usa el endpoint POST /api/auth/recuperarClave para solicitar recuperación
• Sigue el enlace enviado al correo del usuario
• Usa la nueva contraseña temporal como secret

Notas de seguridad

• El secret debe ser tratado como información confidencial
• Para integraciones automatizadas, recomienda usar API Keys en lugar de contraseñas regulares
• Las API Keys pueden ser revocadas individualmente sin afectar el acceso del usuario al sistema