Users

The users module provides a light CRUD for user profiles (read + update), endpoints for reading role and permissions, and avatar upload/delete. GET /users/:user_id is polymorphic: if user_id is omitted the server returns the currently logged-in user’s data; the response shape also differs between web and mobile clients.

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or cookie access_token
Content-Type	application/json · avatar upload: multipart/form-data
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown field → 400
Related modules	authentication, organizations, acl, file-manager
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

FE typically calls GET /users/:user_id without user_id after login to fetch the active user’s profile. GET /users is used by admins to list organization members (or, for the MORIA role, across organizations via org_id). Avatar updates have their own path (POST/DELETE /users/me/profile-image) that writes directly to S3 — profile_image cannot be modified via PATCH /users/:user_id.

Method	Path	Summary
GET	/v1/users	List users (org members / cross-org for MORIA)
GET	/v1/users/monthly-income-range	Reference data for monthly income ranges
GET	/v1/users/:user_id	User detail (or self if param omitted)
PATCH	/v1/users/:user_id	Update user profile
GET	/v1/users/:user_id/role	Fetch the user’s role (without permissions)
GET	/v1/users/:user_id/role/permissions	Fetch the permissions the user holds
POST	/v1/users/me/profile-image	Upload/replace profile picture (multipart)
DELETE	/v1/users/me/profile-image	Remove profile picture

Auth & client notes

• Some endpoints use @RequireClientType() — FE must send X-Client-Type: web or X-Client-Type: mobile. Response shapes differ between the two.
• MORIA users must include org_id in GET /users. ORGANIZATION/INDIVIDUAL users can only scope to their own organization.
• The profile_image field cannot be changed via PATCH — use the dedicated /users/me/profile-image route.

---

GET /v1/users bearer

List users (organization members, or cross-organization for the MORIA role). Standard paginated response. The result shape depends on X-Client-Type (web/mobile).

bearer MORIA, ORGANIZATION, INDIVIDUAL read-user RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
org_id	UUID	—	Required if caller is MORIA. For other roles, defaults to the user’s organization.
page	number	1	Page number
limit	number	10	Records per page
order	'asc' | 'desc'	desc	Order by created_at
user_status	enum UserStatus	optional	active, inactive, suspended
user_type	enum UserType	optional	moria, organization, individual

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Users retrieved successfully",
  "data": {
    "limit": 10,
    "count": 124,
    "currentPage": 1,
    "totalPages": 13,
    "users": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440222",
        "first_name": "Aisha",
        "last_name": "Putri",
        "email": "amal@example.com",
        "user_type": "individual",
        "user_status": "active",
        "organization_id": "660e8400-e29b-41d4-a716-446655440111",
        "created_at": "2026-05-20T09:15:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
400 Bad Request	MORIA calls without org_id
401 Unauthorized	Attempted to view another organization (non-MORIA)
403 Forbidden	Permission mismatch
404 Not Found	Organization not found

---

GET /v1/users/monthly-income-range bearer

Reference data for monthly income ranges for profile/KYC dropdowns. Standard pagination.

bearer MORIA, ORGANIZATION, INDIVIDUAL read-user

Query params

Param	Type	Default	Notes
page	number	1	Page number
limit	number	10	Records per page
order	'asc' | 'desc'	desc	Order by created_at

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Monthly income ranges retrieved successfully",
  "data": {
    "limit": 10,
    "count": 6,
    "currentPage": 1,
    "totalPages": 1,
    "ranges": [
      { "id": "...", "label": "0 – 5.000.000", "min": 0, "max": 5000000 }
    ]
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie
403 Forbidden	Permission mismatch

---

GET /v1/users/:user_id bearer

User detail. If user_id is omitted the server returns the logged-in user’s data. The result shape depends on the caller’s UserType and the X-Client-Type header.

bearer read-user RESOURCE_FETCHED

Path params

Param	Type	Notes
user_id	UUID	Optional. If omitted → active user (self).

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Login user data fetched successfully",
  "data": {
    "user": {
      "id": "770e8400-e29b-41d4-a716-446655440222",
      "first_name": "Aisha",
      "last_name": "Putri",
      "email": "amal@example.com",
      "user_type": "individual",
      "user_status": "active",
      "profile_image": null,
      "phone_number": "+628156489101",
      "organization": { "id": "660e8400-e29b-41d4-a716-446655440111", "name": "Moria Fund" },
      "address": { "country": "Indonesia", "city": "Jakarta" }
    }
  }
}

On mobile clients the role, password, and security.two_factor_authentication_secret fields are stripped from the payload. On web clients the data shape is formatted differently by getUserByIdFormatted.

Errors

Status	When it occurs
400 Bad Request	user_id is not a UUID (if sent)
401 Unauthorized	Attempted to access a user from another organization
403 Forbidden	Permission mismatch
404 Not Found	User not found

---

PATCH /v1/users/:user_id bearer

Update a user profile. Only for users in the same organization. All fields are optional — send only what changes. The profile_image field is intentionally absent from the DTO.

bearer update-user RESOURCE_UPDATED

Path params

Param	Type	Notes
user_id	UUID	ID of the user being updated

Request body — UpdateUserDto (all fields optional)

Field	Type	Notes
first_name, last_name, middle_name	string	Basic identity
phone_number	string	International format (+62…)
id_card_number	string	KTP number (16 digits)
education	enum Education	primary_school, junior_high, senior_high, diploma, bachelor, postgraduate, other
mother_name, relatives	string	Additional KYC data
purpose, source_of_income, montly_income	string	Financial profile (typo montly_income retained)
gender	enum Gender	male, female
date_of_birth	date	ISO 8601 (YYYY-MM-DD)
place_of_birth	string	City of birth
religion	enum Religion	islam, christianity, hinduism, buddhism, confucianism, other
marital_status	enum MaritalStatus	single, married, divorced, widowed
province, city, country, district, subdistrict, village	string	Address
rt, rw, postal_code	string	Address detail
address_type	enum AddressType	Default INDIVIDUAL

Example request

{
  "first_name": "Aisha",
  "phone_number": "+628156489102",
  "marital_status": "married",
  "city": "Bandung"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "User updated successfully",
  "data": {
    "user": {
      "id": "770e8400-e29b-41d4-a716-446655440222",
      "first_name": "Aisha",
      "phone_number": "+628156489102",
      "marital_status": "married",
      "updated_at": "2026-05-20T10:00:00.000Z"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed (invalid enum, bad date format)
401 Unauthorized	Updating a user from another organization
403 Forbidden	Missing update-user permission
404 Not Found	User not found

---

GET /v1/users/:user_id/role bearer

Fetch the role attached to a user (without permissions and role_type). If the user has no role yet, the response is successful with no data field.

bearer read-role RESOURCE_FETCHED

Path params

Param	Type	Notes
user_id	UUID	Target user ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "user role fetched successfully",
  "data": {
    "role": {
      "id": "03be5259-f281-478e-a8d0-e7e825e525f2",
      "name": "organization_admin",
      "description": "Admin role for the organization"
    }
  }
}

If the user has no role: 200 response with message: "No role assigned to this user" and no data field.

Errors

Status	When it occurs
403 Forbidden	Permission mismatch
404 Not Found	User not found

---

GET /v1/users/:user_id/role/permissions bearer

Fetch all permissions the user holds via their role. If they have no role, the response is successful with no data field.

bearer read-permission RESOURCE_FETCHED

Path params

Param	Type	Notes
user_id	string	User ID (no UUID pipe at the controller — still send a valid UUID)

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "user role permissions fetched successfully",
  "data": {
    "permissions": [
      { "id": "...", "name": "read-user" },
      { "id": "...", "name": "update-user" }
    ]
  }
}

Errors

Status	When it occurs
403 Forbidden	Permission mismatch
404 Not Found	User not found

---

POST /v1/users/me/profile-image bearer

Upload or replace the active user’s profile picture. The backend accepts a multipart file (max 5 MB, JPEG/PNG/WebP), uploads to S3 (public-read), removes the old object, and stores the key in the users.profile_image column.

bearer update-user RESOURCE_UPDATED

Request body — multipart/form-data

Field	Type	Required	Notes
file	binary	yes	JPEG / PNG / WebP, maximum size 5 MB

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "profile image updated successfully",
  "data": {
    "profile_image": "users/770e8400.../avatar-1716200000.jpg"
  }
}

Errors

Status	When it occurs
400 Bad Request	Invalid file (empty, unsupported MIME, size > 5 MB)
401 Unauthorized	Invalid Bearer/cookie
403 Forbidden	Missing update-user permission

Side effects

• Upload to S3 (public-read bucket) and remove the old object (if any).
• Update the users.profile_image column with the new key.
• Emit BusinessEvent RESOURCE_UPDATED (impact LOW).

---

DELETE /v1/users/me/profile-image bearer

Delete the active user’s profile picture. The backend removes the S3 object referenced by users.profile_image and clears that column.

bearer update-user RESOURCE_DELETED

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "profile image removed successfully",
  "data": {}
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie
403 Forbidden	Missing update-user permission

Side effects

• Remove S3 object (if any).
• Set users.profile_image = NULL.

---

Reference

Enum: UserStatus

• active, inactive, suspended

Enum: UserType

• moria, organization, individual

Enum: Education

• primary_school, junior_high, senior_high
• diploma, bachelor, postgraduate, other

Enum: Religion

• islam, christianity, hinduism
• buddhism, confucianism, other

Enum: MaritalStatus

• single, married, divorced, widowed

Standard error envelope

{
  "message": "you can't view another organization",
  "statusCode": 401,
  "error": "Unauthorized"
}

message can be a string or an array of strings (multi-field validation errors).

Client-type header

• X-Client-Type: web — “formatted” response shape
• X-Client-Type: mobile — lean shape (no role, password, security)

Common HTTP codes

• 400 body/query/param validation
• 401 cross-organization access
• 403 permission mismatch
• 404 user not found