Login

Authenticate a user with username and password to receive a JWT token

POST /api/auth/login

Login

cURL

curl --request POST \
  --url https://api.example.com/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "username": "<string>",
  "password": "<string>"
}
'

Success Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "username": "johndoe",
  "email": "[e-mail]",
  "role": "RESIDENT",
  "roles": ["RESIDENT"],
  "roleDetails": [
    {
      "id": "7a9b8c3d-1234-5678-90ab-cdef12345678",
      "code": "RESIDENT",
      "description": "Community Resident"
    }
  ],
  "expiresAt": "2026-03-05T15:30:00Z",
  "residentInfo": {
    "id": "9c8b7a6d-5432-1098-76ab-fedcba987654",
    "fullname": "John Doe",
    "email": "[e-mail]",
    "phone": "[phone]",
    "number": "A-101",
    "address": "123 Main Street, Apt 101",
    "comunidades": ["1a2b3c4d-5678-90ab-cdef-1234567890ab"],
    "comunidad": {
      "id": "1a2b3c4d-5678-90ab-cdef-1234567890ab",
      "nombre": "Sunset Community",
      "direccion": "123 Main Street",
      "email": "[e-mail]",
      "phone": "[phone]",
      "tipoComunidad": "Residential",
      "cantidadViviendas": 150
    },
    "comunidadesCompletas": [
      {
        "id": "1a2b3c4d-5678-90ab-cdef-1234567890ab",
        "nombre": "Sunset Community",
        "direccion": "123 Main Street",
        "email": "[e-mail]",
        "phone": "[phone]",
        "tipoComunidad": "Residential",
        "cantidadViviendas": 150
      }
    ]
  }
}

Request Body

username · string · required

User’s username (3-15 characters)

password · string · required

User’s password

Response

token · string

JWT authentication token

userId · string

User’s unique identifier (GUID)

username · string

User’s username

email · string

User’s email address

role · string

User’s primary role (for backward compatibility)

roles · array

List of role codes assigned to the user

roleDetails · array

Detailed information about each role

Show RoleDto

id · string

Role unique identifier (GUID)

code · string

Role code (e.g., “ADMIN”, “RESIDENT”)

description · string

Human-readable role description

expiresAt · string

Token expiration date/time in ISO 8601 format

residentInfo · object

Additional information if user has a resident profile

Show LoginResidentInfoDto

id · string

Resident unique identifier (GUID)

fullname · string

Resident’s full name

email · string

Resident’s email address

phone · string

Resident’s phone number

number · string

Resident’s unit/house number

address · string

Resident’s address

comunidades · array

Array of community IDs (backward compatibility)

comunidad · object

First community details (backward compatibility)

comunidadesCompletas · array

Complete list of communities with full information

Example Request

curl -X POST https://api.happyhabitat.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "SecurePass123"
  }'

Example Response

Success Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "username": "johndoe",
  "email": "[e-mail]",
  "role": "RESIDENT",
  "roles": ["RESIDENT"],
  "roleDetails": [
    {
      "id": "7a9b8c3d-1234-5678-90ab-cdef12345678",
      "code": "RESIDENT",
      "description": "Community Resident"
    }
  ],
  "expiresAt": "2026-03-05T15:30:00Z",
  "residentInfo": {
    "id": "9c8b7a6d-5432-1098-76ab-fedcba987654",
    "fullname": "John Doe",
    "email": "[e-mail]",
    "phone": "[phone]",
    "number": "A-101",
    "address": "123 Main Street, Apt 101",
    "comunidades": ["1a2b3c4d-5678-90ab-cdef-1234567890ab"],
    "comunidad": {
      "id": "1a2b3c4d-5678-90ab-cdef-1234567890ab",
      "nombre": "Sunset Community",
      "direccion": "123 Main Street",
      "email": "[e-mail]",
      "phone": "[phone]",
      "tipoComunidad": "Residential",
      "cantidadViviendas": 150
    },
    "comunidadesCompletas": [
      {
        "id": "1a2b3c4d-5678-90ab-cdef-1234567890ab",
        "nombre": "Sunset Community",
        "direccion": "123 Main Street",
        "email": "[e-mail]",
        "phone": "[phone]",
        "tipoComunidad": "Residential",
        "cantidadViviendas": 150
      }
    ]
  }
}

Error Codes

Status Code	Code	Description
400	VALIDATION_ERROR	Missing or invalid request parameters
401	UNAUTHORIZED	Invalid username or password
500	INTERNAL_ERROR	Internal server error