Users API

import { Badge } from ‘@astrojs/starlight/components’;

Users

GET /api/users

List all staff members in the clinic.

Auth: Admin only

Response 200:

[
  {
    "id": "uuid",
    "email": "staff@clinica.com",
    "full_name": "María González",
    "role": "admin | staff",
    "is_active": true,
    "last_login_at": "2026-05-30T14:30:00Z",
    "created_at": "2026-05-01T00:00:00Z"
  }
]

---

GET /api/users/switchable

List active clinic members for the quick user-switch UI. Returns minimal info (no email) — accessible to any authenticated user.

Auth: Required

Response 200:

[
  { "id": "uuid", "full_name": "Admin Name", "role": "admin" },
  { "id": "uuid", "full_name": "María González", "role": "staff" }
]

---

POST /api/users

Create a new staff member. Generates and returns a one-time password.

Auth: Admin only (enforced by checkUserLimit — Clínica/Forever Free = unlimited; Basic/Pro/Trial = 1 user)

Request:

{
  "fullName": "New Staff Member",
  "email": "newstaff@clinica.com",
  "role": "admin | staff"
}

Response 201:

{
  "id": "uuid",
  "email": "newstaff@clinica.com",
  "full_name": "New Staff Member",
  "role": "staff",
  "is_active": true,
  "created_at": "2026-05-31T00:00:00Z",
  "temporaryPassword": "A1b2C3d4E5fg"
}

Caution

The temporaryPassword is returned exactly once and is never stored in plaintext. Share it with the new staff member immediately — it cannot be recovered. The staff member should change it after first login using PATCH /api/users/me.

Errors:

Status	Code	Reason
403	USER_LIMIT_REACHED	Plan user limit exceeded
409	—	Email already registered globally

---

PATCH /api/users/me

Update your own profile (name and/or password).

Auth: Required

Request (all fields optional):

{
  "full_name": "New Name",
  "currentPassword": "currentPass123",
  "newPassword": "newSecurePass456"
}

To change password, currentPassword is required. newPassword must be ≥ 8 characters.

Response 200:

{
  "id": "uuid",
  "email": "user@clinica.com",
  "full_name": "New Name",
  "role": "staff"
}

Errors:

Status	Message
400	“El nombre debe tener al menos 2 caracteres”
400	“La nueva contraseña debe tener al menos 8 caracteres”
401	“Contraseña actual incorrecta”

---

PATCH /api/users/:id

Update a staff member’s role or active status.

Auth: Admin only

Request (at least one field required):

{
  "role": "admin | staff",
  "is_active": true
}

Guards:

• Cannot deactivate your own account
• Cannot update users from another clinic

Response 200: Updated user object

Errors:

Status	Message
400	“No puedes desactivar tu propia cuenta”
403	“Acceso denegado” (different clinic)
404	“Usuario no encontrado”