Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GianlucaBessone/HDB-Service/llms.txt

Use this file to discover all available pages before exploring further.

The Users API manages platform accounts in HDB Service. Every user has a role drawn from the UserRole enum (ADMIN, SUPERVISOR, TECHNICIAN, CLIENT_RESPONSIBLE, CLIENT_REQUESTER) which controls what data they can see and what actions they can perform. When a new user is created, the system simultaneously registers them in Supabase Auth and in the local PostgreSQL database via Prisma. The user is created with mustChangePassword: true so they are prompted to choose their own password on first login. All users endpoints are restricted to ADMIN role, with GET /api/users also accessible to SUPERVISOR. passwordHash is never included in any response.

​
GET /api/users

Returns all user records. Each record includes the associated client name and the list of plant IDs the user has been granted access to. The passwordHash field is never returned. Required roles: ADMIN, SUPERVISOR
​
role
string
Filter by user role. One of ADMIN, SUPERVISOR, TECHNICIAN, CLIENT_RESPONSIBLE, or CLIENT_REQUESTER.
​
clientId
string
Filter users by their associated client ID.
​
active
boolean
Filter by active status. Pass true for active users only or false for deactivated accounts.
​
id
string
User ID (matches the Supabase Auth user UUID).
​
nombre
string
First name.
​
apellido
string
Last name (nullable).
​
email
string
Email address.
​
role
string
User role: ADMIN, SUPERVISOR, TECHNICIAN, CLIENT_RESPONSIBLE, or CLIENT_REQUESTER.
​
active
boolean
Whether the account is active.
​
clientId
string
Associated client ID (nullable — only set for CLIENT_RESPONSIBLE and CLIENT_REQUESTER).
​
createdAt
string
ISO 8601 account creation timestamp.
​
client
object
​
plantAccess
array
Array of objects, each containing a plantId string. Populated for CLIENT_REQUESTER users; empty for other roles.
curl -X GET "https://your-domain.com/api/users?role=TECHNICIAN" \
  -H "Cookie: sb-access-token=<token>"
Error responses:
StatusDescription
401Not authenticated.
403Authenticated user is not ADMIN or SUPERVISOR.
500Internal server error.

​
POST /api/users

Creates a new user account. The process involves three steps executed in sequence: (1) verify the email does not already exist in the Prisma database; (2) create the user in Supabase Auth with email_confirm: true so no verification email is required; (3) create the Prisma user record with a bcrypt-hashed password and mustChangePassword: true. Plant access entries are created in bulk via UserPlantAccess if plantIds is provided. Required role: ADMIN
​
email
string
required
Email address. Must be unique across all users.
​
nombre
string
required
User’s first name.
​
apellido
string
User’s last name.
​
role
string
required
User role. One of ADMIN, SUPERVISOR, TECHNICIAN, CLIENT_RESPONSIBLE, or CLIENT_REQUESTER.
​
password
string
required
Temporary password. Stored as a bcrypt hash (10 rounds). The user will be prompted to change it on first login.
​
clientId
string
Required when role is CLIENT_RESPONSIBLE or CLIENT_REQUESTER. Associates the user with a specific client.
​
plantIds
string[]
Array of plant IDs to grant access to. Applicable for CLIENT_REQUESTER users. Each entry creates a UserPlantAccess record.
​
id
string
User ID (the Supabase Auth UUID is used as the Prisma primary key).
​
email
string
User email address.
​
nombre
string
First name.
​
apellido
string
Last name (nullable).
​
role
string
Assigned role.
​
active
boolean
Always true on creation.
​
clientId
string
Associated client ID (nullable).
​
mustChangePassword
boolean
Always true on creation.
​
createdAt
string
ISO 8601 creation timestamp.
curl -X POST "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=<token>" \
  -d '{
    "email": "juan.perez@acme.com",
    "nombre": "Juan",
    "apellido": "Pérez",
    "role": "CLIENT_REQUESTER",
    "password": "TempPass123!",
    "clientId": "client_abc",
    "plantIds": ["plant_xyz", "plant_north"]
  }'
The user’s Supabase Auth UUID is reused as the Prisma User.id, so the two records are always in sync and can be looked up by the same ID.
Passwords are stored as bcrypt hashes. Never log or expose the plain-text password value received in the request body.
Error responses:
StatusDescription
400email, nombre, role, or password is missing.
400A user with this email already exists in the database.
400Supabase Auth rejected the creation request (e.g., invalid email format).
401Not authenticated.
403Authenticated user is not ADMIN.
500Internal server error.

​
PATCH /api/users/[id]

Updates one or more fields on an existing user. Only fields present in the request body are modified; omitted fields are left unchanged. If plantIds is included, the existing UserPlantAccess records for this user are fully replaced (all deleted and recreated from the new array). If a new password is provided, it is hashed with bcrypt and mustChangePassword is set to true. Relevant changes (name, role, password) are also synced to Supabase Auth metadata. An ADMIN cannot deactivate their own account (active: false on the currently authenticated user returns 400). Required role: ADMIN
​
nombre
string
Updated first name.
​
apellido
string
Updated last name.
​
role
string
New role. One of ADMIN, SUPERVISOR, TECHNICIAN, CLIENT_RESPONSIBLE, CLIENT_REQUESTER.
​
clientId
string
New client association. Pass null to clear.
​
plantIds
string[]
Full replacement list of plant IDs for access control. All previous UserPlantAccess entries are deleted and replaced with this list.
​
active
boolean
Set to false to deactivate the account.
​
password
string
New password. Will be hashed and will set mustChangePassword: true.
​
id
string
User ID.
​
nombre
string
Updated first name.
​
apellido
string
Updated last name (nullable).
​
email
string
Email address (unchanged).
​
role
string
Updated role.
​
active
boolean
Current active state.
​
clientId
string
Current client association (nullable).
​
mustChangePassword
boolean
Current must-change-password flag.
​
updatedAt
string
ISO 8601 last-updated timestamp.
curl -X PATCH "https://your-domain.com/api/users/usr_abc123" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=<token>" \
  -d '{
    "role": "CLIENT_RESPONSIBLE",
    "clientId": "client_abc",
    "plantIds": []
  }'
Passing plantIds always performs a full replacement — even an empty array [] will remove all existing plant access for the user. Omit the plantIds key entirely if you do not wish to modify plant access.
Error responses:
StatusDescription
400Attempting to deactivate the currently authenticated user’s own account.
404User not found.
401Not authenticated.
403Authenticated user is not ADMIN.
500Internal server error.

​
DELETE /api/users/[id]

Permanently deletes a user account from both the Prisma database and Supabase Auth. An ADMIN cannot delete their own account. This is a hard delete — the record is not soft-deleted. Required role: ADMIN
​
success
boolean
Always true on a successful deletion.
curl -X DELETE "https://your-domain.com/api/users/usr_abc123" \
  -H "Cookie: sb-access-token=<token>"
This endpoint performs a hard delete — the user record is permanently removed from both the application database and Supabase Auth. All associated records (plant access entries, etc.) are cascade-deleted. This action cannot be undone. Consider using PATCH with active: false for reversible deactivation.
Error responses:
StatusDescription
400Attempting to delete the currently authenticated user’s own account.
401Not authenticated.
403Authenticated user is not ADMIN.
500Internal server error.

Build docs developers (and LLMs) love

Get started for freeTalk to us