Users API

Users are managed with the users permission (Super Admin and Admin by default; each action - read, create, update, delete - can be granted on its own in the role editor). The role ladder decides whom you may manage: you can only create, edit, delete or reset the password of a user whose role is less senior (a higher level number) than your own, so an Admin cannot manage a Super Admin or another Admin. You can always edit your own account, but not raise your own role, and you cannot delete it. Passwords are never returned.

GET /api/users

Requires Bearer token + users read permission.

Every user you may see (a user confined to some projects sees the users of those projects), each with their profile fields.

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

GET /api/users/:id

Requires Bearer token. The user themselves, or a role with users read permission.

A single user, with their profile.

// Response 200
{ "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin", "isActive": true, "profile": {} }
// Error 404
{ "error": "User not found" }

POST /api/users

Requires Bearer token + users create permission.

Create a user. You can only give roles (primary and additional) less senior than your own.

Field	Type	Description
name	string	Display name
email	string	Unique email address
password	string	At least 8 characters, plus any rules a plugin such as Security adds
role	string	Optional. Defaults to user.
additionalRoles	array	Optional. More roles; a permission check passes if any role grants it.
projects	array	Optional. Project slugs the user is confined to.
isActive	boolean	Optional. Defaults to true.
profile	object	Optional. Profile field values.

// Response 201
{ "id": "uuid", "name": "Bob", "email": "bob@example.com", "role": "user", "isActive": true }
// Error 403
{ "error": "You cannot create a user with that role" }
// Error 409 - the email is already in use

PUT /api/users/:id

Requires Bearer token + users update permission.

Update a user. Send only the fields to change: name, email, password, role, additionalRoles, projects, isActive, profile. A new password, or switching an account off, ends that user's sessions.

// Response 200 - the updated user, with profile
// Error 403
{ "error": "You cannot edit a user with that role" }

POST /api/users/:id/password-reset

Requires Bearer token + users update permission. Not for your own account.

Start a password reset for someone else: email them a link (the default), or with {"via": "link"} get the link back to pass on yourself - for a site without email. The account must be active and less senior than yours.

// Request body (optional)
{ "via": "email" }   // or "link"
// Response 200
{ "sent": true, "expiresAt": "...", "expiresIn": "1 hour" }
{ "link": "https://example.com/admin/#/reset-password?token=...", "expiresAt": "...", "expiresIn": "1 hour" }
// Error 409 - INACTIVE, NO_SMTP (copy the link instead) or NO_ORIGIN (set the Site URL)
{ "error": "...", "code": "NO_SMTP" }

DELETE /api/users/:id/password-reset

Requires Bearer token + users update permission.

Withdraw an open reset link, so it no longer works.

// Response 200
{ "ok": true }

DELETE /api/users/:id

Requires Bearer token + users delete permission.

Delete a user. You cannot delete your own account or anyone as senior as you.

// Response 200
{ "success": true }
// Error 403
{ "error": "You cannot delete your own account" }