User API

The User API provides endpoints for managing user accounts, profiles, and settings.

Endpoints

Create User

POST /user/

Creates a new user account. Requires the create_user permission.

Request Body

{
  "user_fullname": "string",
  "user_email": "string",
  "user_phonenumber": "string",
  "role_id": "uuid",
  "unit_id": "uuid"
}

Responses

201 Created - User created successfully

href="#__codelineno-2-1">{ "detail": "User created successfully", "user": { "user_id": "uuid", "user_code": "string", "user_fullname": "string", "user_email": "string", "user_phonenumber": "string", "is_active": true, "is_two_factor_auth": false, "role": { "role_id": "uuid", "role_name": "string" }, "unit": { "unit_id": "uuid", "unit_name": "string" } } }

400 Bad Request - Validation error

{
  "detail": "User with this email already exists."
}

or

{
  "detail": "User with this phone number already exists."
}

or

{
  "detail": "User role with ID {role_id} does not exist."
}

or

{
  "detail": "Organizational unit with ID {unit_id} does not exist."
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get Current User Profile

GET /user/profile

Retrieves the profile of the currently authenticated user.

Responses

200 OK - Profile retrieved successfully

{
  "user_id": "uuid",
  "user_code": "string",
  "user_fullname": "string",
  "user_email": "string",
  "user_phonenumber": "string",
  "is_active": true,
  "is_two_factor_auth": false,
  "roles": [
    {
      "role_id": "uuid",
      "role_name": "string",
      "role_description": "string",
      "role_is_active": true
    }
  ],
  "permissions": [
    {
      "permission_id": "uuid",
      "permision_key": "string",
      "permission_name": "string",
      "permission_desc": "string"
    }
  ],
  "organizational_units": [
    {
      "unit_id": "uuid",
      "unit_name": "string",
      "unit_description": "string",
      "is_active": true
    }
  ]
}

401 Unauthorized - Not authenticated

{
  "detail": "Not authenticated"
}

Get All Users

GET /user/allUsers

Retrieves a list of all users with optional filtering. Requires the get_all_users permission.

Query Parameters

Parameter	Type	Description
user_id	UUID	Filter by user ID
user_code	string	Filter by user code
user_fullname	string	Filter by user full name (partial match)
email	string	Filter by email address (partial match)
phone_number	string	Filter by phone number (partial match)
gender	string	Filter by gender
is_active	boolean	Filter by active status (true/false)
is_two_factor_auth	boolean	Filter by two-factor authentication status (true/false)
created_after	datetime	Filter users created after this date and time (ISO 8601 format)
created_before	datetime	Filter users created before this date and time (ISO 8601 format)

Responses

200 OK - Users retrieved successfully

[
  {
    "user_id": "uuid",
    "user_code": "string",
    "user_fullname": "string",
    "user_email": "string",
    "user_phonenumber": "string",
    "is_active": true,
    "is_two_factor_auth": false,
    "roles": [
      {
        "role_id": "uuid",
        "role_name": "string"
      }
    ],
    "organizational_units": [
      {
        "unit_id": "uuid",
        "unit_name": "string"
      }
    ]
  }
]

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Update Two-Factor Authentication

PUT /user/{user_id}/two-factor

Updates the two-factor authentication settings for a user.

Path Parameters

user_id (UUID): ID of the user

Request Body

{
  "is_two_factor_auth": true
}

Responses

200 OK - Settings updated successfully

{
  "detail": "Two-factor authentication settings updated successfully"
}

404 Not Found - User not found

{
  "detail": "User not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get User Profile

GET /user/{user_id}

Retrieves the profile of a specific user. Requires the view_user_profile permission.

Path Parameters

user_id (UUID): ID of the user

Responses

200 OK - Profile retrieved successfully

{
  "user_id": "uuid",
  "user_code": "string",
  "user_fullname": "string",
  "user_email": "string",
  "user_phonenumber": "string",
  "is_active": true,
  "is_two_factor_auth": false,
  "roles": [
    {
      "role_id": "uuid",
      "role_name": "string",
      "role_description": "string",
      "role_is_active": true
    }
  ],
  "permissions": [
    {
      "permission_id": "uuid",
      "permision_key": "string",
      "permission_name": "string",
      "permission_desc": "string"
    }
  ],
  "organizational_units": [
    {
      "unit_id": "uuid",
      "unit_name": "string",
      "unit_description": "string",
      "is_active": true
    }
  ]
}

404 Not Found - User not found

{
  "detail": "User not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Update User

PUT /user/{user_id}

Updates a user's information. Requires the update_user permission.

Path Parameters

user_id (UUID): ID of the user to update

Request Body

{
  "user_fullname": "string",
  "user_email": "string",
  "user_phonenumber": "string",
  "role_id": "uuid",
  "unit_id": "uuid"
}

Responses

200 OK - User updated successfully

{
  "detail": "User updated successfully."
}

404 Not Found - User not found

{
  "detail": "User with ID {user_id} does not exist."
}

400 Bad Request - Validation error

{
  "detail": "User with this email already exists."
}

or

{
  "detail": "User with this phone number already exists."
}

or

{
  "detail": "User role with ID {role_id} does not exist."
}

or

{
  "detail": "Organizational unit with ID {unit_id} does not exist."
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Update User Status

PUT /user/{user_id}/status

Updates a user's active status. Requires the activate_deactivate_user permission.

Path Parameters

user_id (UUID): ID of the user

Request Body

{
  "is_active": true
}

Responses

200 OK - Status updated successfully

{
  "detail": "User status updated successfully."
}

404 Not Found - User not found

{
  "detail": "User with ID {user_id} does not exist."
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

User Creation Process

When a new user is created:

The system validates that the email and phone number are unique
The system validates that the specified role and organizational unit exist
A unique user code is generated for the user
A random password is generated
The user account is created with the provided information
The user is assigned to the specified role and organizational unit
An email is sent to the user with their user code and temporary password

Two-Factor Authentication

Users can enable or disable two-factor authentication for their accounts:

When enabled, users must enter an OTP after password verification during login
When disabled, users can log in with just their username and password
The setting can be toggled via the /user/{user_id}/two-factor endpoint

User Status Management

User accounts can be activated or deactivated:

Active users can log in and access the system
Inactive users are prevented from logging in
User status can be updated via the /user/{user_id}/status endpoint