User endpoints — auth, profile, and account

All user state in the LMS Backend revolves around a single User document. Authentication is cookie-based: on a successful sign-in or sign-up the server sets an HTTP-only token cookie containing a signed JWT. Protected endpoints verify this cookie via the isAuthenticated middleware — you do not need to pass Authorization headers manually if your HTTP client forwards cookies.

All endpoints are prefixed with /api/v1/user. The base URL for local development is http://localhost:4000.

Create a new user account. The validateSignUp middleware runs before the controller and rejects requests that fail field validation. Auth required: No

Request body

name

string

required

Display name. Maximum 50 characters.

string

required

Valid email address. Stored in lowercase. Must be unique across all accounts.

password

string

required

Account password. Minimum 8 characters. Stored as a bcrypt hash.

role

string

default:"student"

Account role. Accepted values: student, instructor, admin. Defaults to student.

Response

success

boolean

true on successful account creation.

message

string

Human-readable confirmation message.

user

object

The newly created user object. Does not include password.

Show user fields

_id

string

MongoDB document ID.

name

string

Display name.

string

Lowercase email address.

role

string

student, instructor, or admin.

avatar

string

URL or filename of the profile avatar. Default: "default-avatar.png".

bio

string

Optional biography text.

enrolledCourses

array

List of enrolled course references with enrolledAt timestamps.

createdCourses

array

List of course IDs created by the user (instructors).

lastActive

string

ISO 8601 datetime of last activity.

totalEnrolledCourses

number

Virtual field — count of enrolled courses.

createdAt

string

ISO 8601 document creation timestamp.

updatedAt

string

ISO 8601 last-update timestamp.

token

string

The signed JWT. Also delivered as the token HTTP-only cookie. You do not need to store this manually if your client handles cookies automatically.

curl --request POST \
  --url http://localhost:4000/api/v1/user/signup \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "password": "securepass123"
  }'

Errors

Status	Condition
`400`	Validation failed (missing or malformed fields)
`400`	A user with that email already exists

Authenticate an existing user. On success, sets an HTTP-only token cookie that must be included in all subsequent protected requests. Auth required: No

Request body

string

required

Registered email address.

password

string

required

Account password in plain text. Compared against the stored bcrypt hash.

Response

success

boolean

true on successful authentication.

message

string

Welcome message including the user’s name.

user

object

The authenticated user object (same shape as signup response — does not include password).

token

string

The signed JWT. Also delivered as the token HTTP-only cookie.

curl --request POST \
  --url http://localhost:4000/api/v1/user/signin \
  --header 'Content-Type: application/json' \
  --cookie-jar cookies.txt \
  --data '{
    "email": "ada@example.com",
    "password": "securepass123"
  }'

Use --cookie-jar cookies.txt with cURL to persist the token cookie. Subsequent requests can then use --cookie cookies.txt to send it automatically.

Errors

Status	Condition
`401`	Invalid email or password

POST /api/v1/user/signout

Clear the token cookie to end the current session. Auth required: No (cookie is cleared regardless of its validity)

Response

{
  "success": true,
  "message": "Signed out successfully"
}

curl --request POST \
  --url http://localhost:4000/api/v1/user/signout \
  --cookie cookies.txt

GET /api/v1/user/profile

Retrieve the authenticated user’s full profile. The enrolledCourses array is populated with title, thumbnail, and description from each linked course. Auth required: Yes

Response

success

boolean

true on success.

data

object

The user document with enrolled courses populated and the virtual totalEnrolledCourses count appended.

Show user fields

_id

string

MongoDB document ID.

name

string

Display name.

string

Email address.

role

string

Account role.

avatar

string

Avatar URL or filename.

bio

string

Biography text.

enrolledCourses

array

Array of enrollment objects.

Show enrollment object

course

object

Populated course with _id, title, thumbnail, and description.

enrolledAt

string

ISO 8601 enrollment timestamp.

totalEnrolledCourses

number

Count of all enrolled courses.

lastActive

string

ISO 8601 last-activity datetime.

curl --request GET \
  --url http://localhost:4000/api/v1/user/profile \
  --cookie cookies.txt

Errors

Status	Condition
`401`	Missing or invalid auth cookie
`404`	Authenticated user not found in database

PATCH /api/v1/user/profile

Update the authenticated user’s profile. Send as multipart/form-data if you are uploading a new avatar image; otherwise application/json is accepted for text-only fields. Auth required: Yes

Request — multipart/form-data

name

string

Updated display name.

string

Updated email address. Stored lowercase.

bio

string

Biography text. Maximum 200 characters.

avatar

file

New avatar image file. When provided, the old avatar is deleted from Cloudinary and replaced with the newly uploaded image. The field name must be avatar.

Response

success

boolean

true on success.

message

string

"Profile updated successfully."

data

object

The updated user document.

curl --request PATCH \
  --url http://localhost:4000/api/v1/user/profile \
  --cookie cookies.txt \
  --form 'name=Ada Lovelace' \
  --form 'bio=Mathematician and writer' \
  --form 'avatar=@/path/to/photo.jpg'

Errors

Status	Condition
`401`	Missing or invalid auth cookie
`404`	Authenticated user not found

PATCH /api/v1/user/password

Change the password for the authenticated account. Auth required: Yes

Request body

newPassword

string

required

The replacement password. Minimum 8 characters. Saved as a new bcrypt hash.

Response

{
  "success": true,
  "message": "Password changed successfully."
}

curl --request PATCH \
  --url http://localhost:4000/api/v1/user/password \
  --cookie cookies.txt \
  --header 'Content-Type: application/json' \
  --data '{"newPassword": "newSecurePass456"}'

Errors

Status	Condition
`400`	`newPassword` is missing from the request body
`401`	Missing or invalid auth cookie
`404`	User not found

POST /api/v1/user/forgot-password

Generate a short-lived password reset token for the given email address. In the current implementation the raw token is returned directly in the response body — in production you would email it to the user instead. Auth required: No

Request body

string

required

The email address associated with the account that needs a password reset.

Response

success

boolean

true when a token is generated.

message

string

"Password reset token generated successfully"

data

object

Show data properties

token

string

The raw (unhashed) reset token. Valid for 10 minutes. Pass this value in the URL of the reset-password endpoint.

curl --request POST \
  --url http://localhost:4000/api/v1/user/forgot-password \
  --header 'Content-Type: application/json' \
  --data '{"email": "ada@example.com"}'

Errors

Status	Condition
`400`	Email field is missing
`404`	No account found for that email

POST /api/v1/user/reset-password/:token

Reset the account password using a valid token obtained from the forgot-password endpoint. The token is valid for 10 minutes from the time it was generated. Auth required: No

Path parameters

token

string

required

The raw reset token returned by POST /api/v1/user/forgot-password.

Request body

newPassword

string

required

The new password. Minimum 8 characters.

Response

{
  "success": true,
  "message": "Password reset successfully. You can now log in with your new password."
}

curl --request POST \
  --url http://localhost:4000/api/v1/user/reset-password/YOUR_RESET_TOKEN \
  --header 'Content-Type: application/json' \
  --data '{"newPassword": "freshNewPass789"}'

Errors

Status	Condition
`400`	Token is missing from path
`400`	`newPassword` is missing
`400`	Token is invalid or has expired (older than 10 minutes)

DELETE /api/v1/user/account

Permanently delete the authenticated user’s account. If the user has a custom avatar stored in Cloudinary, it is also deleted. The operation is irreversible. Auth required: Yes

Response

success

boolean

true on successful deletion.

message

string

"User account deleted successfully"

data

object

The deleted user document as it existed before removal.

curl --request DELETE \
  --url http://localhost:4000/api/v1/user/account \
  --cookie cookies.txt

Account deletion is permanent. All user data is removed from the database and any associated Cloudinary avatar is deleted. There is no recovery path.

Errors

Status	Condition
`401`	Missing or invalid auth cookie
`404`	User not found

Overview

Endpoints

User endpoints — auth, profile, and account

Request body

Response

Errors

Request body

Response

Errors

POST /api/v1/user/signout

Response

GET /api/v1/user/profile

Response

Errors

PATCH /api/v1/user/profile

Request — multipart/form-data

Response

Errors

PATCH /api/v1/user/password

Request body

Response

Errors

POST /api/v1/user/forgot-password

Request body

Response

Errors

POST /api/v1/user/reset-password/:token

Path parameters

Request body

Response

Errors

DELETE /api/v1/user/account

Response

Errors

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/v1/user/signup

​Request body

​Response

​Errors

​POST /api/v1/user/signin

​Request body

​Response

​Errors

​POST /api/v1/user/signout

​Response

​GET /api/v1/user/profile

​Response

​Errors

​PATCH /api/v1/user/profile

​Request — multipart/form-data

​Response

​Errors

​PATCH /api/v1/user/password

​Request body

​Response

​Errors

​POST /api/v1/user/forgot-password

​Request body

​Response

​Errors

​POST /api/v1/user/reset-password/:token

​Path parameters

​Request body

​Response

​Errors

​DELETE /api/v1/user/account

​Response

​Errors

Build docs developers (and LLMs) love

POST /api/v1/user/signup

Request body

Response

Errors

POST /api/v1/user/signin

Request body

Response

Errors

POST /api/v1/user/signout

Response

GET /api/v1/user/profile

Response

Errors

PATCH /api/v1/user/profile

Request — multipart/form-data

Response

Errors

PATCH /api/v1/user/password

Request body

Response

Errors

POST /api/v1/user/forgot-password

Request body

Response

Errors

POST /api/v1/user/reset-password/:token

Path parameters

Request body

Response

Errors

DELETE /api/v1/user/account

Response

Errors