Users API — Create, List, Update Roles, and Delete

The Node.js API exposes four user-management endpoints under the /users path. Every endpoint requires a valid JWT in the Authorization: Bearer header and a minimum role of COMPANY_ADMIN. The requests a caller can perform — and the data they can see — are automatically scoped to their company and role level, making it safe to expose these endpoints to company-level administrators without risking cross-tenant data access.

Role hierarchy

QualityDocD defines six roles arranged in ascending order of privilege. The requireMinRole middleware compares a numeric weight assigned to each role, granting access only when the caller’s weight is greater than or equal to the required minimum.

Role	Weight	Description
`VIEWER`	1	Read-only access to documents
`COMMENTER`	2	Read access plus the ability to comment
`CONTRIBUTOR`	3	Can upload documents (land in `DRAFT` status)
`OPERATOR`	4	Manages documents within their module
`COMPANY_ADMIN`	5	Full control within their own company
`SUPER_ADMIN`	6	Full control across all companies

All four user endpoints require a minimum role of COMPANY_ADMIN (weight 5). Callers with VIEWER, COMMENTER, CONTRIBUTOR, or OPERATOR roles receive 403 Forbidden.

A COMPANY_ADMIN can only manage users within their own company, and can only assign or create roles below their own level (up to OPERATOR). Only a SUPER_ADMIN can create or promote COMPANY_ADMIN accounts.

GET /users

Lists user accounts. The result set is automatically scoped by the caller’s role: a COMPANY_ADMIN sees only users belonging to their own company, while a SUPER_ADMIN sees all users across every company. Authentication: Authorization: Bearer <token> — minimum role COMPANY_ADMIN No request body or query parameters. Example request

curl http://localhost:5000/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

200 — Success

[
  {
    "id": 7,
    "companyId": 3,
    "name": "Admin User",
    "email": "admin@company.com",
    "role": "COMPANY_ADMIN",
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  {
    "id": 8,
    "companyId": 3,
    "name": "Jane Operator",
    "email": "jane@company.com",
    "role": "OPERATOR",
    "createdAt": "2025-02-20T14:15:00.000Z"
  }
]

number

The user’s primary key in the users table.

companyId

number

The ID of the company this user belongs to.

name

string

The user’s display name.

string

The user’s email address. Unique across all users in the database.

role

string

The user’s current role. One of VIEWER, COMMENTER, CONTRIBUTOR, OPERATOR, COMPANY_ADMIN, SUPER_ADMIN.

createdAt

string

ISO 8601 timestamp (with timezone) of when the account was created.

Error responses

Status	Condition
`401 Unauthorized`	Missing or invalid `Authorization` header
`403 Forbidden`	Caller’s role is below `COMPANY_ADMIN`

POST /users

Creates a new user account. The new user is associated with a companyId provided in the request body, but a COMPANY_ADMIN caller is restricted: they can only create users in their own company and only assign roles up to and including OPERATOR. A SUPER_ADMIN may create users in any company with any role. Authentication: Authorization: Bearer <token> — minimum role COMPANY_ADMIN

companyId

number

required

The ID of the company the new user will belong to. If the caller is a COMPANY_ADMIN, this must match their own companyId; any other value results in 403 Forbidden.

name

string

required

The new user’s display name.

string

required

The new user’s email address. Must be unique across all users in the database.

password

string

required

The new user’s plaintext password. Hashed with bcrypt (10 rounds) before being stored. Never returned in any response.

role

string

The role to assign. One of VIEWER, COMMENTER, CONTRIBUTOR, OPERATOR, COMPANY_ADMIN, SUPER_ADMIN. Defaults to VIEWER if omitted.A COMPANY_ADMIN caller may only assign VIEWER, COMMENTER, CONTRIBUTOR, or OPERATOR. Attempting to assign COMPANY_ADMIN or SUPER_ADMIN returns 403 Forbidden.

Example request

curl -X POST http://localhost:5000/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": 3,
    "name": "New Operator",
    "email": "newop@company.com",
    "password": "Secure456!",
    "role": "OPERATOR"
  }'

201 — Created

{
  "id": 15,
  "companyId": 3,
  "name": "New Operator",
  "email": "newop@company.com",
  "role": "OPERATOR"
}

number

The newly created user’s primary key.

companyId

number

The company the new user was created in.

name

string

The new user’s display name.

string

The new user’s email address.

role

string

The role assigned to the new user.

Error responses

Status	Condition
`400 Bad Request`	Missing or invalid fields in the request body
`401 Unauthorized`	Missing or invalid `Authorization` header
`403 Forbidden`	Caller is `COMPANY_ADMIN` and the requested `role` exceeds `OPERATOR`, or `companyId` does not match the caller’s own company

The passwordHash column is never exposed by any API response. The plaintext password you send is only ever held in memory long enough to be hashed and discarded.

PUT /users/:id/role

Updates the role of an existing user identified by their numeric id in the URL path. Role changes are validated against the caller’s own role: a COMPANY_ADMIN cannot promote any user to COMPANY_ADMIN or higher, and can only modify users within their own company. Authentication: Authorization: Bearer <token> — minimum role COMPANY_ADMIN URL parameter

Parameter	Type	Description
`id`	`number`	The primary key of the user whose role will be changed

role

string

required

The new role to assign. Must be one of VIEWER, COMMENTER, CONTRIBUTOR, OPERATOR, COMPANY_ADMIN, SUPER_ADMIN.A COMPANY_ADMIN caller may only assign roles below COMPANY_ADMIN (weight ≤ 4): VIEWER, COMMENTER, CONTRIBUTOR, or OPERATOR.

Example request

curl -X PUT http://localhost:5000/users/8/role \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"role": "CONTRIBUTOR"}'

200 — Success

{
  "id": 8,
  "name": "Jane Operator",
  "email": "jane@company.com",
  "role": "CONTRIBUTOR"
}

number

The updated user’s primary key.

name

string

The updated user’s display name.

string

The updated user’s email address.

role

string

The user’s role after the update.

Error responses

Status	Condition
`400 Bad Request`	The `role` value is not one of the six valid role strings
`401 Unauthorized`	Missing or invalid `Authorization` header
`403 Forbidden`	Caller is `COMPANY_ADMIN` and the target user is in a different company, or the requested `role` is `COMPANY_ADMIN` or higher
`404 Not Found`	No user exists with the given `id`

DELETE /users/:id

Permanently deletes a user account. The caller cannot delete their own account. A COMPANY_ADMIN can only delete users within their own company; attempting to delete a user from another company returns 403 Forbidden. A SUPER_ADMIN can delete any user across all companies. Authentication: Authorization: Bearer <token> — minimum role COMPANY_ADMIN URL parameter

Parameter	Type	Description
`id`	`number`	The primary key of the user to delete

Example request

curl -X DELETE http://localhost:5000/users/8 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

200 — Success

{
  "deleted": true
}

deleted

boolean

Always true when the request succeeds, confirming the user record was removed from the database.

Error responses

Status	Condition
`400 Bad Request`	The `id` in the URL matches the caller’s own user ID (self-deletion is not allowed)
`401 Unauthorized`	Missing or invalid `Authorization` header
`403 Forbidden`	Caller is `COMPANY_ADMIN` and the target user belongs to a different company
`404 Not Found`	No user exists with the given `id`

Deletion is permanent and immediate. There is no soft-delete or recovery mechanism. Ensure you are targeting the correct user id before calling this endpoint.

Authentication

Documents

Platform

Users API — Create, List, Update Roles, and Delete

Role hierarchy

GET /users

POST /users

PUT /users/:id/role

DELETE /users/:id

Build docs developers (and LLMs) love

Authentication

Documents

Platform

Documentation Index

​Role hierarchy

​GET /users

​POST /users

​PUT /users/:id/role

​DELETE /users/:id

Build docs developers (and LLMs) love

Role hierarchy

GET /users

POST /users

PUT /users/:id/role

DELETE /users/:id