Users

The Users API provides endpoints to manage user accounts, including creating staff members, assigning roles and permissions, and managing user profiles.

Authentication

All endpoints require authentication with the MANAGE_USERS permission.

User Roles

The system supports the following roles:

admin - Full system access
doctor - Medical professionals with clinical access
receptionist - Front desk staff with appointment and patient management
assistant - Clinical assistants with limited access

Endpoints

List Users

curl -X GET "https://your-domain.com/api/users" \
  -H "Cookie: session=your-session-token"

Retrieve a list of all users in the system.

success

boolean

Indicates if the request was successful

users

array

Array of user objects

Show user object

integer

Unique user identifier

name

string

User’s full name

username

string

Username for login

string

Email address

role

string

User role (admin, doctor, receptionist, assistant)

branch_id

integer

Primary branch assignment

initials

string

User initials

status

string

Account status (active, inactive)

specialty

string

Medical specialty (for doctors)

license_number

string

Professional license number (for doctors)

doctor_branch_ids

array

Array of branch IDs where doctor works (for doctors)

created_at

string

Account creation timestamp

{
  "success": true,
  "users": [
    {
      "id": 1,
      "name": "Admin User",
      "username": "admin",
      "email": "[email protected]",
      "role": "admin",
      "branch_id": 1,
      "initials": "AU",
      "status": "active",
      "specialty": null,
      "license_number": null,
      "doctor_branch_ids": [],
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 5,
      "name": "Dr. Sarah Smith",
      "username": "drssmith",
      "email": "[email protected]",
      "role": "doctor",
      "branch_id": 1,
      "initials": "DS",
      "status": "active",
      "specialty": "Orthodontics",
      "license_number": "ODO-12345",
      "doctor_branch_ids": [1, 2],
      "created_at": "2024-01-10T08:00:00Z"
    },
    {
      "id": 8,
      "name": "John Receptionist",
      "username": "jreception",
      "email": "[email protected]",
      "role": "receptionist",
      "branch_id": 1,
      "initials": "JR",
      "status": "active",
      "specialty": "General",
      "license_number": "",
      "doctor_branch_ids": [],
      "created_at": "2024-02-01T09:00:00Z"
    }
  ]
}

Create User

curl -X POST "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-token" \
  -d '{
    "name": "Dr. Emily Rodriguez",
    "username": "dremily",
    "email": "[email protected]",
    "password": "SecurePass123!",
    "role": "doctor",
    "branch_id": 1,
    "specialty": "Periodontics",
    "license_number": "PER-54321",
    "branch_ids": [1, 2]
  }'

Create a new user account.

name

string

required

User’s full name

username

string

required

Username for login (must be unique)

string

required

Email address

password

string

required

Password (will be hashed before storage)

role

string

required

User role: “admin”, “doctor”, “receptionist”, or “assistant”

branch_id

integer

Primary branch assignment

specialty

string

Medical specialty (for doctors, default: “General”)

license_number

string

Professional license number (for doctors)

branch_ids

array

Array of branch IDs where doctor works (for doctors)

{
  "success": true,
  "message": "Usuario creado exitosamente"
}

When creating a user, default permissions are automatically assigned based on their role using the ROLE_PERMISSIONS mapping.

Update User

curl -X PATCH "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-token" \
  -d '{
    "id": 5,
    "name": "Dr. Sarah Smith-Jones",
    "username": "drssmith",
    "email": "[email protected]",
    "role": "doctor",
    "status": "active",
    "branch_id": 1,
    "specialty": "Orthodontics & Pediatric Dentistry",
    "license_number": "ODO-12345",
    "branch_ids": [1, 2, 3]
  }'

Update an existing user’s information.

integer

required

User ID to update

name

string

required

User’s full name

username

string

required

Username for login

string

required

Email address

role

string

required

User role

status

string

Account status: “active” or “inactive”

branch_id

integer

Primary branch assignment

specialty

string

Medical specialty (for doctors)

license_number

string

Professional license number (for doctors)

branch_ids

array

Array of branch IDs (for doctors)

{
  "success": true,
  "message": "Usuario actualizado"
}

If the user’s role is “doctor”, the system automatically updates the doctor profile with specialty, license number, and branch assignments.

Delete User

curl -X DELETE "https://your-domain.com/api/users?id=8" \
  -H "Cookie: session=your-session-token"

Delete a user account from the system.

integer

required

ID of the user to delete

{
  "success": true,
  "message": "Usuario eliminado"
}

Users cannot delete their own account. The system prevents self-deletion to avoid accidentally losing administrator access.

User Initials

The system automatically generates user initials from their name:

Takes the first letter of each word
Converts to uppercase
Limits to 2 characters for regular users, 3 for doctors

Examples:

“John Smith” → “JS”
“Dr. Emily Rodriguez” → “DE” (or “DER” for doctors)
“Sarah” → “SA”

Role-Based Permissions

When creating a user, default permissions are assigned based on role: Admin Role:

Full system access
All permissions granted

Doctor Role:

View and manage patients
View and manage appointments
View and create medical records
View and edit odontograms
View reports

Receptionist Role:

View patients
Create and manage appointments
View schedules
Basic patient information access

Assistant Role:

View patients
View appointments
Limited clinical access

Doctor-Specific Fields

When the role is “doctor”, additional fields become relevant:

specialty

string

Medical specialty (e.g., “Orthodontics”, “Endodontics”, “Periodontics”)

license_number

string

Professional license or registration number

branch_ids

array

Array of branch IDs where the doctor provides services. A doctor can work at multiple branches.

Common Use Cases

Create Admin User

curl -X POST "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-token" \
  -d '{
    "name": "Jane Admin",
    "username": "jadmin",
    "email": "[email protected]",
    "password": "SecurePassword!",
    "role": "admin",
    "branch_id": 1
  }'

Create Doctor with Multiple Branches

curl -X POST "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-token" \
  -d '{
    "name": "Dr. Michael Chen",
    "username": "drchen",
    "email": "[email protected]",
    "password": "SecurePass123!",
    "role": "doctor",
    "branch_id": 1,
    "specialty": "Oral Surgery",
    "license_number": "OS-99999",
    "branch_ids": [1, 2, 3]
  }'

Create Receptionist

curl -X POST "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-token" \
  -d '{
    "name": "Maria Garcia",
    "username": "mgarcia",
    "email": "[email protected]",
    "password": "SecurePass123!",
    "role": "receptionist",
    "branch_id": 2
  }'

Update User Status

curl -X PATCH "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-token" \
  -d '{
    "id": 8,
    "name": "John Receptionist",
    "username": "jreception",
    "email": "[email protected]",
    "role": "receptionist",
    "status": "inactive",
    "branch_id": 1
  }'

Change User Role

curl -X PATCH "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-token" \
  -d '{
    "id": 10,
    "name": "Robert Assistant",
    "username": "rassist",
    "email": "[email protected]",
    "role": "receptionist",
    "status": "active",
    "branch_id": 1
  }'

Error Responses

{
  "message": "No autorizado"
}

Security Considerations

Password Handling

All passwords are hashed using bcrypt with a cost factor of 10
Passwords are never returned in API responses
Password changes require appropriate permissions

Self-Deletion Prevention

Users cannot delete their own account
System checks currentUser.id !== id before allowing deletion

Permission Enforcement

All endpoints check for MANAGE_USERS permission
Role-based access control is enforced at the API level

Doctors API - Specialized doctor management
Branches API - Branch assignments

Source Reference

API implementation can be found in:

src/routes/api/users/+server.js - All user management endpoints
$lib/permissions.js - Role permissions mapping

Overview

Endpoints

Authentication

User Roles

Endpoints

List Users

Create User

Update User

Delete User

User Initials

Role-Based Permissions

Doctor-Specific Fields

Common Use Cases

Create Admin User

Create Doctor with Multiple Branches

Create Receptionist

Update User Status

Change User Role

Error Responses

Security Considerations

Password Handling

Self-Deletion Prevention

Permission Enforcement

Source Reference

Build docs developers (and LLMs) love

Overview

Endpoints

​Authentication

​User Roles

​Endpoints

​List Users

​Create User

​Update User

​Delete User

​User Initials

​Role-Based Permissions

​Doctor-Specific Fields

​Common Use Cases

​Create Admin User

​Create Doctor with Multiple Branches

​Create Receptionist

​Update User Status

​Change User Role

​Error Responses

​Security Considerations

​Password Handling

​Self-Deletion Prevention

​Permission Enforcement

​Related Endpoints

​Source Reference

Build docs developers (and LLMs) love

Authentication

User Roles

Endpoints

List Users

Create User

Update User

Delete User

User Initials

Role-Based Permissions

Doctor-Specific Fields

Common Use Cases

Create Admin User

Create Doctor with Multiple Branches

Create Receptionist

Update User Status

Change User Role

Error Responses

Security Considerations

Password Handling

Self-Deletion Prevention

Permission Enforcement

Related Endpoints

Source Reference