Skip to main content

​
Endpoint

POST /login
Authenticates a user with email and password, returning a JWT token on success. The endpoint also sets HTTP-only cookies for session management.

​
Request

​
email
string
required
User’s email address
​
password
string
required
User’s password (plain text, will be compared against bcrypt hash)

​
Request Format

The endpoint expects form data (application/x-www-form-urlencoded or multipart/form-data).

​
Response

​
token
string
JWT token for authenticated requests (user ID)
​
status
boolean
Authentication status: true on success
​
error
null
Always null on successful authentication

​
Example Request

curl -X POST http://localhost:8080/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]" \
  -d "password=securePassword123" \
  -c cookies.txt

​
Example Responses

{
  "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": true,
  "error": null
}
Additionally, the following cookies are set:
  • Bearer: HTTP-only cookie containing JWT token (24h expiration)
  • user: Cookie containing user ID (24h expiration)
{
  "error": "the password provided is not valid"
}
Common error scenarios:
  • Invalid email (user not found)
  • Incorrect password
  • Account not active (status != "active")
  • Database connection issues

​
Authentication Flow

​
1. User Lookup

The system retrieves the user from MongoDB using GetUserByEmail(): 
user, err := users.GetUserByEmail(email)

​
2. Status Verification

User status must be “active”: 
if user.Status != "active" {
  return "", false, fmt.Errorf("user is not active")
}
Valid statuses:
  • active: Can log in
  • pending: Registration incomplete
  • Other statuses: Access denied

​
3. Password Verification

Password is compared against bcrypt hash: 
err := bcrypt.CompareHashAndPassword(user.Password, []byte(password))

​
4. Token Generation

On success, the user’s ID is returned as the token: 
return user.ID, true, nil

​
Session Management

The login endpoint sets cookies for session management:
  • Name: Bearer
  • Value: JWT token
  • Expires: 24 hours from login
  • Path: /
  • HttpOnly: true (prevents XSS access)
  • Name: user
  • Value: User ID
  • Expires: 24 hours from login
  • Path: /
  • HttpOnly: false

​
Source Code References

  • Handler: backend/auth/routes.go:13 - HandleUserLogin
  • Logic: backend/auth/controller.go:13 - processUserLogin
  • Model: backend/users/model.go:47 - GetUserByEmail

​
Error Handling

All errors return HTTP status 401 with error details:
  • User Not Found: GetUserByEmail returns MongoDB “not found” error
  • Inactive Account: “user is not active”
  • Invalid Password: “the password provided is not valid”

​
Security Considerations

  • Passwords are verified using bcrypt.CompareHashAndPassword
  • HTTP-only cookies prevent XSS attacks on tokens
  • Only “active” users can authenticate
  • No timing attacks: bcrypt comparison is constant-time
  • Token expires after 24 hours

Build docs developers (and LLMs) love

Get started for freeTalk to us