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

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