Saltar a contenido

Autenticación

Cuatro flujos comparten una misma URL base: el inicio de sesión del usuario, el refresco del token, la recuperación de contraseña y el token OAuth para clientes registrados.

Comprobar un usuario

POST /auth/check-user
Campo Obligatorio Significado
workspace sí El espacio donde buscar
username sí El nombre de usuario 
{"exists": true,
 "user": {"username": "admin", "name": "Administrator admin", "workspace": "starter", "status": "ACTIVE"},
 "auth": {"type": "local", "source": null}}

auth.type indica cómo inicia sesión el usuario. local significa la contraseña de la plataforma; cualquier otro valor significa una fuente de autenticación externa, y la llamada de inicio de sesión se comporta distinto.

Iniciar sesión

POST /auth/login
Campo Obligatorio Significado
workspace sí El espacio
username sí El nombre de usuario
password sí La contraseña
timezone_offset no El desfase del cliente, usado para las fechas que se muestran después
user_lang no Un idioma preferido para la respuesta
remember_me no Mantener la sesión más tiempo 
{"success": true,
 "uid": "…",
 "redirect_url": "/starter/en/lurana/adminPanel/main?page=modern#/home/inbox",
 "tokens": {"access_token": "…", "refresh_token": "…", "token_type": "bearer", "expires_in": 300},
 "user": {"uid": "…", "username": "admin", "fullname": "Administrator admin", "role": "LURANA_ADMIN", "workspace": "starter"}}

La respuesta también trae un bloque timezone: cuando mismatch es verdadero, la zona del cliente difiere de la guardada para el usuario, y la lista de timezones se ofrece para que el cliente la corrija con auth/update-timezone.

Un inicio de sesión fallido devuelve success: false con el motivo; no devuelve tokens.

Refrescar

POST /auth/token/refresh
Campo Obligatorio
refresh_token sí

Devuelve un par nuevo de acceso y refresco. El token de refresco también expira, así que un cliente que queda inactivo más que su vida útil debe iniciar sesión otra vez.

Actualizar la zona horaria

POST /auth/update-timezone
Campo Significado
timezone El nombre IANA, por ejemplo America/La_Paz

Recuperación de contraseña

Tres llamadas, en este orden:

Llamada Campos Resultado
POST /auth/forgot-password workspace, username, email, locale Envía el mensaje de restablecimiento
POST /auth/validate-reset-token token Dice si el token sigue siendo válido
POST /auth/reset-password token, password, password_confirmation Fija la contraseña nueva

La llamada de recuperación verifica que el usuario exista y que el correo coincida, y necesita un servidor de correo configurado; sin él responde que no hay servidor disponible.

Token OAuth

POST /oauth/token

Endpoint estándar de OAuth2 para un cliente registrado: client_credentials, authorization_code o refresh_token. Las credenciales del cliente salen de la pantalla de clientes OAuth.

Un grant no soportado responde 400 con error: unsupported_grant_type, que es la causa habitual de una petición que parece correcta y no devuelve nada.

Usar el token

Authorization: Bearer <access_token>

Un token ausente, mal formado o expirado responde 401 con {"success":false,"error":"SESSION_EXPIRED"}.

Dentro del navegador la aplicación también puede enviar la cookie de sesión en lugar del token; así llaman a la API sus propias pantallas. Una integración externa debe usar siempre el token.

Relacionado