Users API: list and manage platform user accounts

The Users API gives administrators full control over platform accounts — listing all users, creating new ones, updating roles and creator store details, and permanently deleting accounts. All endpoints except PUT (which also accepts CREADOR callers updating their own store profile) are restricted to the ADMIN role.

GET /api/users ADMIN

Returns all registered users ordered by createdAt descending. Each user entry includes their linked CreatorStore if they hold the CREADOR role.

Response

{
  "success": true,
  "users": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "email": "user@example.com",
      "role": "CLIENTE",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "creatorStore": null
    },
    {
      "id": "a9b8c7d6-e5f4-3210-fedc-ba9876543210",
      "email": "creator@example.com",
      "role": "CREADOR",
      "createdAt": "2024-02-15T09:30:00.000Z",
      "creatorStore": {
        "id": "...",
        "slug": "mi-tienda",
        "displayName": "Mi Tienda Creativa",
        "bio": "Diseños únicos hechos a mano.",
        "active": true
      }
    }
  ]
}

success

boolean

Always true on success.

users

array

Array of all registered user objects. passwordHash is never included in this response.

Show User response fields

string

UUID of the user.

string

Unique email address used for authentication.

role

string

Platform role. One of CLIENTE, CREADOR, TALLER, or ADMIN.

createdAt

string

ISO 8601 timestamp of account creation.

creatorStore

object | null

Linked CreatorStore record if the user is a CREADOR; null otherwise.

POST /api/users ADMIN

Create a new user account from the admin dashboard. The password is hashed server-side before being stored. The email is normalized to lowercase and trimmed before uniqueness is checked.

Request body

string

required

Email address for the new account. Must be unique across all users. Stored in lowercase.

password

string

required

Plain-text password. Hashed server-side using hashPassword before storage. Never logged or returned.

role

string

required

Initial role for the account. Accepted values: CLIENTE, CREADOR, TALLER, ADMIN.

Response

{
  "success": true,
  "userId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123"
}

Error responses

Status	Condition
`400`	`email`, `password`, or `role` missing.
`400`	Email is already registered.
`401` / `403`	Caller does not hold the `ADMIN` role.
`500`	Unexpected server error.

PUT /api/users

Update a user’s role, email, password, or creator store settings. Admins may update any user. CREADOR users may update only their own record — they cannot change their own role, email, or password via this endpoint; only storeInfo is permitted for self-updates.

Request body

string

required

UUID of the user to update.

string

New email address. Normalized to lowercase. Admins only.

role

string

New role assignment. Accepted values: CLIENTE, CREADOR, TALLER, ADMIN. Admins only.

password

string

New plain-text password. Hashed before storage. Admins only.

storeInfo

object

Creator store configuration. Only applied when role is "CREADOR". If the user does not yet have a Creator or CreatorStore record, both are created automatically.

Show storeInfo fields

displayName

string

Public display name for the creator’s storefront.

slug

string

URL-safe slug used to identify the store (e.g., "mi-tienda").

bio

string

Short biography shown on the storefront.

active

boolean

Whether the store is publicly visible. Defaults to true.

Response

{ "success": true }

Error responses

Status	Condition
`400`	`id` missing.
`401` / `403`	Caller lacks the required role, or a `CREADOR` is attempting to modify fields they do not own.
`500`	Unexpected server error.

DELETE /api/users?id= ADMIN

Permanently delete a user account. This is a hard delete — the record is removed from the database along with all dependent data subject to onDelete: Cascade rules. If the user has orders or other non-cascading relations the database operation may fail; in that case the deletion falls back to the local file store only.

Query parameters

string

required

UUID of the user to delete.

Response

{ "success": true }

Error responses

Status	Condition
`400`	`id` query parameter missing.
`401` / `403`	Caller does not hold the `ADMIN` role.
`500`	Unexpected server error.

User model reference

The following fields are available on the User Prisma model. Fields marked Admin-visible are returned by GET /api/users; passwordHash is never exposed through the API.

Field	Type	Description
`id`	`String` (UUID)	Primary key. Auto-generated on creation.
`email`	`String`	Unique email address. Used for login and communications.
`role`	`Role`	Platform role. Determines access across all API endpoints.
`createdAt`	`DateTime`	Timestamp when the account was first created.
`updatedAt`	`DateTime`	Timestamp of the most recent change to the record.
`creatorProfile`	`Creator?`	Linked `Creator` record present when `role` is `CREADOR`. Includes an `approved` boolean and a nested `store` (`CreatorStore`).
`workshopUser`	`WorkshopUser?`	Links a `TALLER`-role user to their assigned `Workshop`.

Role values

Value	Description
`CLIENTE`	Standard customer. Can place orders and submit payment receipts.
`CREADOR`	Creator partner. Can upload designs and manage a public storefront. Requires `Creator.approved = true` before the store goes live.
`TALLER`	Workshop operator. Linked to a `Workshop` via `WorkshopUser`. Receives production assignments.
`ADMIN`	Platform administrator. Unrestricted access to all API endpoints.

Role changes take effect on the user’s next login session — the JWT issued at their previous login still carries the old role claim until it expires (24 hours). To change a user’s role immediately, update it via PUT /api/users with the role field and ask the user to log out and back in.

Authentication

Endpoints

Users API: list and manage platform user accounts

GET /api/users ADMIN

Response

POST /api/users ADMIN

Request body

Response

Error responses

PUT /api/users

Request body

Response

Error responses

DELETE /api/users?id= ADMIN

Query parameters

Response

Error responses

User model reference

Role values

Build docs developers (and LLMs) love

Authentication

Endpoints

Documentation Index

​GET /api/users ADMIN

​Response

​POST /api/users ADMIN

​Request body

​Response

​Error responses

​PUT /api/users

​Request body

​Response

​Error responses

​DELETE /api/users?id= ADMIN

​Query parameters

​Response

​Error responses

​User model reference

​Role values

Build docs developers (and LLMs) love

GET /api/users ADMIN

Response

POST /api/users ADMIN

Request body

Response

Error responses

PUT /api/users

Request body

Response

Error responses

DELETE /api/users?id= ADMIN

Query parameters

Response

Error responses

User model reference

Role values