Skip to main content
POST
/
api
/
v1
/
auth
/
login
Login
curl --request POST \
  --url https://api.example.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "username": "<string>",
  "password": "<string>"
}
'
{
  "status": "<string>",
  "message": "<string>",
  "user": {
    "user.id": "<string>",
    "user.username": "<string>",
    "user.email": "<string>",
    "user.active": true,
    "user.role_id": 123,
    "user.role_name": "<string>"
  }
}

​
Overview

The login endpoint authenticates users by validating their username and password credentials. Upon successful authentication, it returns the user’s profile information. Note that JWT token generation is planned for a future release (Epic 3.2).

​
Request

​
username
string
required
The username of the user attempting to log in
​
password
string
required
The user’s password

​
Example Request

curl -X POST https://api.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "securePassword123"
  }'

​
Response

​
status
string
Status of the request. Returns “success” for successful authentication
​
message
string
Human-readable message describing the result
​
user
object
User profile information
​
user.id
string
Unique identifier for the user
​
user.username
string
The user’s username
​
user.email
string
The user’s email address
​
user.active
boolean
Whether the user account is active
​
user.role_id
integer
The ID of the user’s role
​
user.role_name
string
The name of the user’s role (e.g., “admin”, “manager”, “employee”)

​
Example Response

{
  "status": "success",
  "message": "Login exitoso",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "john_doe",
    "email": "[email protected]",
    "active": true,
    "role_id": 2,
    "role_name": "manager"
  }
}

​
Error Responses

​
status
string
Returns “error” when authentication fails
​
message
string
Description of the error

​
400 Bad Request

Returned when required fields are missing: 
{
  "status": "error",
  "message": "Body requerido."
}

{
  "status": "error",
  "message": "Username y password son requeridos."
}

​
401 Unauthorized

Returned when credentials are invalid or user is inactive: 
{
  "status": "error",
  "message": "Credenciales inválidas"
}

​
500 Internal Server Error

Returned when an unexpected error occurs: 
{
  "status": "error",
  "message": "Error interno del servidor"
}

​
Implementation Reference

The login endpoint is implemented in backend/Auth/Adapters/auth_controller.py:14-46: 
@router.route('/login', methods=['POST'])
def login():
    """Endpoint para iniciar sesión."""
    try:
        data = request.get_json()
        if not data:
            return jsonify({"status": "error", "message": "Body requerido."}), 400

        username = data.get('username')
        password = data.get('password')

        if not username or not password:
            return jsonify({"status": "error", "message": "Username y password son requeridos."}), 400

        db = next(get_db())
        service = _get_service(db)
        
        user = service.login(username, password)
        
        return jsonify({
            "status": "success",
            "message": "Login exitoso",
            "user": user.to_dict()
        }), 200

    except ValueError as ve:
        return jsonify({"status": "error", "message": str(ve)}), 401
    except Exception as e:
        logger.error("Error inesperado en login: %s", e)
        return jsonify({"status": "error", "message": "Error interno del servidor"}), 500

Build docs developers (and LLMs) love

Get started for freeTalk to us