Users API

API Reference

Role hierarchy governs which users can manage other users. A manager cannot create, edit, or delete an admin. Self-deletion is always blocked.

Requires Bearer token + users permission (admin or manager).

Return all users. Passwords are stripped from the response.

// Response 200
[ { "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin", "isActive": true } ]

Requires Bearer token. Accessible to the user themselves, or a user with users permission.

Return a single user by ID.

// Response 200
{ "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin", "isActive": true }

// Error 404
{ "error": "User not found" }

Requires Bearer token + users permission.

Create a new user. The actor cannot assign a role higher than their own level.

Field	Type	Description
`name`	string	Display name
`email`	string	Unique email address
`password`	string	Minimum 8 characters
`role`	string	Optional. Defaults to `editor`.

// Response 201
{ "id": "uuid", "name": "Bob", "email": "bob@example.com", "role": "editor", "isActive": true }

// Error 409
{ "error": "Email already in use" }

Requires Bearer token + users permission.

Update a user's details. Managers cannot edit admins. Role escalation beyond the actor's own level is blocked.

Field	Type	Description
`name`	string	New display name
`email`	string	New email address
`password`	string	New password (min 8 chars)
`role`	string	New role
`isActive`	boolean	Enable or disable the account

// Response 200 — returns the updated user object

Requires Bearer token + users permission.

Delete a user. Cannot delete your own account or a user with a higher role level.

// Response 200
{ "success": true }

// Error 403
{ "error": "You cannot delete your own account" }