Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/juadariasmar/inventory_project/llms.txt

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

The Users API manages the members of your tenant company. Users are authenticated through Neon Auth — each Usuario record in the database is linked to a Neon Auth identity via neonAuthId. Administrators can list all members, adjust roles and fine-grained permissions, change a user’s estado (active, suspended, or pending), and remove accounts. An invitation system allows admins to onboard new members by sending tokenized email invitations that recipients accept through a dedicated endpoint.
All user management endpoints (/api/usuarios and /api/usuarios/[id]) require the ADMIN role. Requests from users with the USUARIO role return 403 Forbidden. An admin cannot delete their own account — attempting to do so returns 400 Bad Request.

​
Endpoints

MethodPathDescription
GET/api/usuariosList all users in the tenant (ADMIN only)
POST/api/usuariosCreate a user record directly (ADMIN only)
GET/api/usuarios/[id]Get a user by ID (ADMIN only)
PUT/api/usuarios/[id]Update a user’s role, permissions, or state (ADMIN only)
DELETE/api/usuarios/[id]Delete a user (ADMIN only; cannot delete self)
GET/api/invitacionesList all invitations for the tenant
POST/api/invitacionesSend an invitation email to a new member
POST/api/invitaciones/aceptarAccept an invitation using a token
GET/api/invitaciones/validarValidate an invitation token before rendering the accept UI
GET/api/empresa/usuariosList all users in the company including pending members

​
GET /api/usuarios

Returns all Usuario records for the tenant, ordered by creation date descending. Each record exposes id, email, nombre, rol, estado, and creadoEn.

​
Response fields

​
id
string
Internal user UUID (cuid).
​
email
string
User email address, synchronized from Neon Auth.
​
nombre
string
Display name.
​
rol
string
Role assigned to the user: ADMIN or USUARIO.
​
estado
string
Account state: PENDIENTE, ACTIVO, or SUSPENDIDO.
​
creadoEn
string
ISO 8601 timestamp of user record creation.
curl -b 'session=...' \
  'https://your-domain.com/api/usuarios'

​
POST /api/usuarios

Creates a Usuario record directly in the database under the tenant. This is intended for administrative provisioning; the created account starts with a placeholder Neon Auth ID and must complete the Neon Auth sign-in flow to become fully active. Requires ADMIN role. Returns the created user (HTTP 201).

​
Request body

​
email
string
required
User email address. Must be unique across the system.
​
nombre
string
required
Display name for the user.
​
rol
string
Role to assign: ADMIN or USUARIO. Defaults to USUARIO if omitted or unrecognized.
​
permisos
array
Array of Permiso enum values to grant. Unrecognized values are silently filtered out. Accepted values: VER_ANALISIS, EXPORTAR_REPORTES, REGISTRAR_MOVIMIENTOS, REALIZAR_VENTAS.

​
Response fields

​
id
string
Assigned user ID (cuid).
​
email
string
Email address.
​
nombre
string
Display name.
​
rol
string
Assigned role.
​
estado
string
Initial state: PENDIENTE.
​
permisos
array
Granted permissions.
​
creadoEn
string
Creation timestamp (ISO 8601).
curl -b 'session=...' \
  -X POST 'https://your-domain.com/api/usuarios' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "nombre": "Laura Gómez",
    "rol": "USUARIO",
    "permisos": ["VER_ANALISIS", "REALIZAR_VENTAS"]
  }'

​
GET /api/usuarios/[id]

Returns a single user by their internal ID. The lookup is scoped to the tenant. Returns 404 if the user does not exist within the company. Requires ADMIN role.

​
Path parameters

​
id
string
required
User UUID (cuid).

​
Response fields

​
id
string
User ID.
​
email
string
Email address.
​
nombre
string
Display name.
​
rol
string
Assigned role.
​
estado
string
Account state.
​
permisos
array
Array of granted Permiso values.
​
creadoEn
string
Creation timestamp (ISO 8601).
curl -b 'session=...' \
  'https://your-domain.com/api/usuarios/clxxxxxxxxxxxxxxxxxxxxxxx'

​
PUT /api/usuarios/[id]

Updates a user’s profile, role, permissions, or account state. Only the fields provided in the body are changed. Permission changes are validated against the known Permiso enum — unknown values are silently dropped. Requires ADMIN role. The full updated user object is returned.

​
Path parameters

​
id
string
required
User UUID (cuid).

​
Request body

​
nombre
string
Updated display name.
​
email
string
Updated email address. Must be unique across the system.
​
rol
string
Updated role: ADMIN or USUARIO. Other values are ignored.
​
permisos
array
Replacement permissions array. Accepted values: VER_ANALISIS, EXPORTAR_REPORTES, REGISTRAR_MOVIMIENTOS, REALIZAR_VENTAS.
​
estado
string
Updated account state: PENDIENTE, ACTIVO, or SUSPENDIDO. Use SUSPENDIDO to block a user’s access without deleting their record.
curl -b 'session=...' \
  -X PUT 'https://your-domain.com/api/usuarios/clxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "estado": "SUSPENDIDO",
    "permisos": []
  }'

​
DELETE /api/usuarios/[id]

Permanently deletes a user from the tenant. The requesting admin cannot delete their own account — that attempt returns 400 Bad Request. The operation validates that the target user belongs to the same company before deleting. Returns { "ok": true } on success. Requires ADMIN role.

​
Path parameters

​
id
string
required
User UUID (cuid) of the account to delete.
curl -b 'session=...' \
  -X DELETE 'https://your-domain.com/api/usuarios/clxxxxxxxxxxxxxxxxxxxxxxx'

​
GET /api/invitaciones

Lists all invitations belonging to the tenant. Available to any active tenant member.

​
Response fields

Returns an array of Invitacion objects, each including id, email, rol, estado, expiraEn, and creadoEn. 
curl -b 'session=...' \
  'https://your-domain.com/api/invitaciones'

​
POST /api/invitaciones

Sends a tokenized invitation email to a new member. The invitation record is created with estado: PENDIENTE and an expiry timestamp. The token is embedded in the email link and used to accept the invitation. Requires ADMIN role.

​
Request body

​
email
string
required
Email address of the person being invited.
​
rol
string
Role to pre-assign when the invitation is accepted: ADMIN or USUARIO. Defaults to USUARIO.
curl -b 'session=...' \
  -X POST 'https://your-domain.com/api/invitaciones' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "rol": "USUARIO"
  }'

​
POST /api/invitaciones/aceptar

Accepts a pending invitation using the token received in the invitation email. On success, the invitation’s estado is set to ACEPTADA and the corresponding Usuario record is created and linked to the Neon Auth identity.

​
Request body

​
token
string
required
Unique invitation token from the email link.
​
neonAuthId
string
required
The Neon Auth user ID obtained after completing the Neon Auth sign-up flow.
​
email
string
required
Email address confirmed during sign-up.
​
nombre
string
required
Display name provided during sign-up.
curl -X POST 'https://your-domain.com/api/invitaciones/aceptar' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "clyyyyyyyyyyyyyyyyyyyyy",
    "neonAuthId": "nauth_zzzzzzzzzzzzzzzzz",
    "email": "[email protected]",
    "nombre": "Nuevo Miembro"
  }'

​
GET /api/invitaciones/validar

Validates an invitation token and returns its metadata before the accept form is rendered. Returns 404 for an expired or already-used token.

​
Query parameters

​
token
string
required
Invitation token to validate.

​
Response fields

​
valida
boolean
Always true when the token is valid.
​
email
string
Email address the invitation was sent to.
​
empresaNombre
string
Name of the company associated with the invitation.
​
expiraEn
string
ISO 8601 expiry timestamp.
curl 'https://your-domain.com/api/invitaciones/validar?token=clyyyyyyyyyyyyyyyyyyyyy'

​
GET /api/empresa/usuarios

Returns the users in the current company as an object containing a usuarios array and an esAdmin flag indicating whether the requesting user is an admin. Includes users with any estado (PENDIENTE, ACTIVO, SUSPENDIDO), ordered by creation date ascending.

​
Response fields

​
usuarios
array
Array of user objects for the company.
​
usuarios[].id
string
User ID.
​
usuarios[].email
string
Email address.
​
usuarios[].nombre
string
Display name.
​
usuarios[].rol
string
Assigned role.
​
usuarios[].estado
string
Account state: PENDIENTE, ACTIVO, or SUSPENDIDO.
​
esAdmin
boolean
true if the authenticated user has the ADMIN or SUPER_ADMIN role.
curl -b 'session=...' \
  'https://your-domain.com/api/empresa/usuarios'

​
Permiso enum values

The following permission values are recognized by the system. They can be granted to any user regardless of role and control access to specific features in the UI and API.
ValueDescription
VER_ANALISISAccess the analytics dashboard (GET /api/analisis).
EXPORTAR_REPORTESDownload Excel reports (GET /api/analisis/exportar).
REGISTRAR_MOVIMIENTOSCreate manual stock movements.
REALIZAR_VENTASCreate sales and quotations.

Build docs developers (and LLMs) love

Get started for freeTalk to us