Staff API
The staff module holds the admin area accounts, the staff groups that give them permissions, and the staff sign-in (password, email PIN, authenticator app, passkey, password reset). See Staff for groups and permissions and Sign-in security for the sign-in steps.
Admin calls need Module access on the Staff card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”get_list
Section titled “get_list”POST /api/admin/staff/get_list
Lists staff members, by ID.
Permission: View staff details (staff.view)
| Parameter | Type | Description |
|---|---|---|
search |
string | Text in the name or email. |
status |
string | active or inactive. |
id |
integer | Only the staff member with this ID. |
no_cron |
boolean | Leave out the system cron account. Default true. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has id, email, name, system_name (cron for the system cron account, else null), status, signature, timezone, created_at, updated_at, twofactor (authenticator app on), passkeys (how many; 0 while passkeys are off for staff) and groups (each as group_get returns it).
Example
Request parameters:
{ "status": "active", "per_page": 1}result:
{ "pages": 3, "page": 1, "per_page": 1, "total": 3, "list": [ { "id": 3, "email": "anna@example.com", "name": "Anna Lee", "system_name": null, "status": "active", "signature": "Anna, Example Hosting support", "timezone": "Europe/Berlin", "created_at": "2026-01-10 09:00:00", "updated_at": "2026-11-17 08:00:00", "twofactor": true, "passkeys": 1, "groups": [ { "id": 3, "name": "Support Staff", "system_name": "support_staff", "parent_id": 2, "parent_name": "Support Lead", "path": "Super Administrator / Support Lead / Support Staff", "depth": 2, "permissions": { "support": { "access": true } }, "protected": false, "created_at": "2026-01-10 09:00:00", "updated_at": "2026-01-10 09:00:00" } ] } ]}get_pairs
Section titled “get_pairs”POST /api/admin/staff/get_pairs
Returns staff members’ IDs and names, by name, for a select list.
Permission: View staff details (staff.view)
| Parameter | Type | Description |
|---|---|---|
search |
string | Text in the name or email. |
per_page |
integer | How many, default 30. |
Returns: An object: staff ID => name. It includes inactive staff and the system cron account.
Example
Request parameters:
{ "search": "anna"}result:
{ "3": "Anna Lee"}POST /api/admin/staff/get
Returns one staff member.
Permission: View staff details (staff.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The staff member’s ID. |
Returns: An object with the fields of a get_list row.
Errors:
- ID was not passed
- Staff member not found
twofactor_disable
Section titled “twofactor_disable”POST /api/admin/staff/twofactor_disable
Turns off a staff member’s two-factor sign-in with the authenticator app, for example after a lost phone.
Permission: Only a Super Administrator may call it (with access to the Staff module).
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The staff member’s ID. |
Returns: true
Errors:
- Only Super Administrators can switch off two-factor sign-in. (code 403)
- Staff member not found
- Two-factor sign-in is not on.
passkeys_remove
Section titled “passkeys_remove”POST /api/admin/staff/passkeys_remove
Removes all of a staff member’s passkeys, for example after a lost device.
Permission: Only a Super Administrator may call it (with access to the Staff module).
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The staff member’s ID. |
Returns: true
Errors:
- Only Super Administrators can remove passkeys of staff. (code 403)
- Staff member not found
- This login has no passkeys.
is_super_administrator
Section titled “is_super_administrator”POST /api/admin/staff/is_super_administrator
Says whether the caller is a Super Administrator.
No parameters.
Returns: true or false.
update
Section titled “update”POST /api/admin/staff/update
Changes a staff member’s details. Only the fields you send change. Setting the status to inactive signs the staff member out and removes their API key.
Permission: Create and edit staff members (staff.create_and_edit_staff). Staff who are not Super Administrators may change only staff whose groups are all below their own, and not themselves. Nobody changes their own email here, Super Administrators included: use profile/update.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The staff member’s ID. |
email |
string | A new sign-in email. Password reset links sent to the old address stop working. |
name |
string | Name. |
status |
string | active or inactive; any other value is refused. |
signature |
string | Ticket reply signature. |
timezone |
string | A time zone such as Europe/Berlin; empty for the site’s default. |
Returns: true
Errors:
- ID was not passed
- Staff member not found
- You cannot deactivate your own staff account
- You cannot manage your own staff account here
- You can only manage staff accounts in lower groups
- Cannot remove the last active super administrator
- Unknown status.
- Invalid timezone:
Fires onBeforeAdminStaffUpdate and onAfterAdminStaffUpdate.
Example
Request parameters:
{ "id": 3, "status": "inactive"}result:
truedelete
Section titled “delete”POST /api/admin/staff/delete
Deletes a staff member, with their group memberships, two-factor setting and passkeys.
Permission: Delete staff members (staff.delete_staff). Staff who are not Super Administrators may delete only staff whose groups are all below their own.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The staff member’s ID. |
Returns: true
Errors:
- Staff member not found
- The cron administrator account cannot be removed
- You can only manage staff accounts in lower groups
- Cannot remove the last active super administrator
This cannot be undone. Fires onBeforeAdminStaffDelete and onAfterAdminStaffDelete.
change_password
Section titled “change_password”POST /api/admin/staff/change_password
Sets a new password for a staff member and signs them out everywhere. Their password reset links stop working.
Permission: Reset staff passwords (staff.reset_staff_password). Staff who are not Super Administrators may do this only for staff whose groups are all below their own. Nobody sets their own password here, Super Administrators included: use profile/change_password.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The staff member’s ID. |
password |
string, required | 8 to 256 characters, with a number, a lowercase and an uppercase letter. |
password_confirm |
string, required | The same password again. |
Returns: true
Errors:
- Password required / Password confirmation required
- Passwords do not match.
- Minimum password length is 8 characters. (and the other password strength messages)
- Staff member not found
- You cannot manage your own staff account here
- You can only manage staff accounts in lower groups
Fires onBeforeAdminStaffPasswordChange and onAfterAdminStaffPasswordChange.
create
Section titled “create”POST /api/admin/staff/create
Adds a staff member in a staff group.
Permission: Create and edit staff members (staff.create_and_edit_staff). Staff who are not Super Administrators may add staff only to groups below their own.
| Parameter | Type | Description |
|---|---|---|
email |
string, required | Sign-in email; it must not be in use by another staff member. |
password |
string, required | 8 to 256 characters, with a number, a lowercase and an uppercase letter. |
name |
string, required | Name. |
group_id |
integer, required | The staff group, which sets the permissions. |
status |
string | active or inactive. Default inactive: send active for an account that can sign in. |
signature |
string | Ticket reply signature. |
timezone |
string | A time zone such as Europe/Berlin. |
Returns: The new staff member’s ID.
Errors:
- Email address was not passed / Password was not passed / Name was not passed / Group ID was not passed
- Group not found
- You can only manage lower staff groups
- Staff member with email
is already registered. (code 788954)
Fires onBeforeAdminStaffCreate and onAfterAdminStaffCreate.
Example
Request parameters:
{ "email": "sam@example.com", "password": "Example-Pass-2026", "name": "Sam Park", "group_id": 4, "status": "active"}result:
7group_get_pairs
Section titled “group_get_pairs”POST /api/admin/staff/group_get_pairs
Returns the staff groups as IDs and their full paths, for a select list.
Permission: View staff details (staff.view)
No parameters.
Returns: An object: group ID => path, such as "3": "Super Administrator / Support Lead / Support Staff".
group_get_list
Section titled “group_get_list”POST /api/admin/staff/group_get_list
Lists the staff groups as a tree: each group followed by its subgroups.
Permission: Manage groups (staff.manage_groups)
| Parameter | Type | Description |
|---|---|---|
search |
string | Text in the group name. |
Returns: An object with list: the groups (not paged), each as group_get returns it.
group_create
Section titled “group_create”POST /api/admin/staff/group_create
Adds a staff group with no permissions yet. Set them with group_update.
Permission: Manage groups (staff.manage_groups), and only a Super Administrator may call it
| Parameter | Type | Description |
|---|---|---|
name |
string, required | The group’s name. |
parent_id |
integer | The parent group. Default: the Super Administrator group. |
Returns: The new group’s ID.
Errors:
- Group name was not passed
- Group not found (the parent)
- Only super administrators can manage staff groups (code 403)
Example
Request parameters:
{ "name": "Billing Staff", "parent_id": 1}result:
6group_get
Section titled “group_get”POST /api/admin/staff/group_get
Returns one staff group with its permissions.
Permission: Manage groups (staff.manage_groups)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The group’s ID. |
Returns: An object: id, name, system_name (set for the built-in groups, such as Super Administrator), parent_id, parent_name, path (the names from the top, joined by /), depth, permissions (module => an object with access and the module’s permission keys), protected (a built-in group that cannot be changed or deleted), created_at and updated_at.
Errors:
- Group ID was not passed
- Group not found
group_delete
Section titled “group_delete”POST /api/admin/staff/group_delete
Deletes an empty staff group.
Permission: Manage groups (staff.manage_groups), and only a Super Administrator may call it
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The group’s ID. |
Returns: true
Errors:
- Group not found
- Only super administrators can manage staff groups (code 403)
- Protected staff groups cannot be removed
- Cannot remove group which has staff members
- Cannot remove group which is used to restrict email templates
- Cannot remove group which has child groups
group_update
Section titled “group_update”POST /api/admin/staff/group_update
Changes a staff group’s name, parent or permissions. Only the fields you send change.
Permission: Manage groups (staff.manage_groups), and only a Super Administrator may call it
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The group’s ID. |
name |
string | A new name. |
parent_id |
integer | A new parent group; not the group itself or one of its subgroups. |
permissions |
object | The group’s full permissions, replacing the old ones: module name => an object with access (true to open the module) and the permission keys to give, such as {"invoice": {"access": true, "view": true}}. The keys are on each module’s API page. |
Returns: true
Errors:
- Group not found
- Only super administrators can manage staff groups (code 403)
- Protected staff groups cannot be modified
- Staff groups must have a parent group
- Parent group not found
- A group cannot be its own parent
- A group cannot use one of its subgroups as parent
- Parameter “permissions” must be an array
Example
Request parameters:
{ "id": 6, "permissions": { "invoice": { "access": true, "view": true }, "client": { "access": true } }}result:
truegroup_member_add
Section titled “group_member_add”POST /api/admin/staff/group_member_add
Adds a staff member to a staff group. A staff member can be in several groups and gets the permissions of all of them.
Permission: Manage groups (staff.manage_groups). Staff who are not Super Administrators may do this only for staff and groups below their own.
| Parameter | Type | Description |
|---|---|---|
admin_id |
integer, required | The staff member’s ID. |
group_id |
integer, required | The group’s ID. |
Returns: true (also when already a member).
Errors:
- Staff member not found
- Group not found
- You can only manage staff accounts in lower groups
- You can only manage lower staff groups
group_member_remove
Section titled “group_member_remove”POST /api/admin/staff/group_member_remove
Removes a staff member from a staff group.
Permission: Manage groups (staff.manage_groups). Staff who are not Super Administrators may do this only for staff and groups below their own.
| Parameter | Type | Description |
|---|---|---|
admin_id |
integer, required | The staff member’s ID. |
group_id |
integer, required | The group’s ID. |
Returns: true (also when not a member).
Errors:
- Staff member not found
- Group not found
- Cannot remove the last active super administrator
group_member_get_list
Section titled “group_member_get_list”POST /api/admin/staff/group_member_get_list
Lists the members of a staff group.
Permission: Manage groups (staff.manage_groups)
| Parameter | Type | Description |
|---|---|---|
group_id |
integer, required | The group’s ID. |
Returns: A list of staff members (not paged), each as get returns it.
Errors:
- Group ID was not passed
- Group not found
admin_group_get_list
Section titled “admin_group_get_list”POST /api/admin/staff/admin_group_get_list
Lists the staff groups a staff member belongs to.
Permission: Manage groups (staff.manage_groups)
| Parameter | Type | Description |
|---|---|---|
admin_id |
integer, required | The staff member’s ID. |
Returns: A list of groups, each as group_get returns it.
Errors:
- Staff member ID was not passed
- Staff member not found
login_history_get_list
Section titled “login_history_get_list”POST /api/admin/staff/login_history_get_list
Lists staff sign-ins, newest first (Staff Login History).
Permission: Manage settings (staff.manage_settings)
| Parameter | Type | Description |
|---|---|---|
search |
string | Text in the staff member’s name, ID or email. |
admin_id |
integer | Only sign-ins of this staff member. |
ip |
string | Part of the IP address. |
date_from |
string | First day to include. |
date_to |
string | Last day to include. |
id |
integer | Only the sign-in with this ID. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has id, ip, created_at, network and browser (kept while the sign-in history or the new-location PIN is on), and staff (id, name, email) when the staff member still exists.
login_history_get
Section titled “login_history_get”POST /api/admin/staff/login_history_get
Returns one staff sign-in.
Permission: Manage settings (staff.manage_settings)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The sign-in’s ID. |
Returns: An object with the fields of a login_history_get_list row.
Errors:
- Event ID was not passed
- Event not found
Guest calls
Section titled “Guest calls”login (guest)
Section titled “login (guest)”POST /api/guest/staff/login
Signs a staff member in to the admin area with email and password, starting a session. When a second step is needed, the sign-in waits for it instead.
| Parameter | Type | Description |
|---|---|---|
email |
string, required | The staff member’s email. |
password |
string, required | The password. |
g-recaptcha-response |
string | The CAPTCHA answer while a reCAPTCHA is on (cf-turnstile-response for Turnstile, h-captcha-response for hCaptcha). |
Returns: Signed in: an object with id, email and name. Waiting for the authenticator app code: {"clientfence_2fa": true} (send it with login_code). Waiting for the email PIN: {"clientfence_pin": true} (send it with login_pin).
Errors:
- Check your login details (code 403)
- You are not allowed to login to admin area from this IP address. (code 403)
- Staff sign-in is not allowed from your location. (code 403)
- You have to complete the CAPTCHA to continue (and the other CAPTCHA messages)
- Your IP address (
) is blocked. Please contact our support to lift your block. (code 403)
A browser call: it needs POST, the session’s CSRF token (CSRFToken or the X-CSRF-TOKEN header) and a same-site origin, and it is limited to 10 tries an hour per IP address. Fires onBeforeAdminLogin, onAfterAdminLogin or onEventAdminLoginFailed.
Example
Request parameters:
{ "email": "anna@example.com", "password": "…"}result:
{ "id": 3, "email": "anna@example.com", "name": "Anna Lee"}login_pin (guest)
Section titled “login_pin (guest)”POST /api/guest/staff/login_pin
Finishes a staff sign-in that waits for the email PIN.
| Parameter | Type | Description |
|---|---|---|
pin |
string, required | The PIN from the email (valid 10 minutes). |
trust |
boolean | true to skip the second step in this browser for 30 days. |
Returns: An object with id, email and name of the signed-in staff member.
Errors:
- Your sign-in has expired. Please sign in again. (code 401)
- The PIN is not correct.
- Too many wrong PINs. Please sign in again. (code 401)
- Too many wrong PINs. Please try again later. (code 429)
- Check your login details (code 403)
- Staff sign-in is not allowed from your location. (code 403)
A browser call in the same session as login: it needs POST, the CSRF token and a same-site origin.
login_pin_resend (guest)
Section titled “login_pin_resend (guest)”POST /api/guest/staff/login_pin_resend
Emails a new PIN for the staff sign-in that waits for one. The old PIN stops working.
No parameters.
Returns: An object: email (where it went, partly hidden), resend_in (seconds until another may be sent), minutes (how long the PIN works) and trust_days.
Errors:
- Your sign-in has expired. Please sign in again. (code 401)
- Please wait a minute before asking for a new PIN. (code 429)
- Too many PINs for this sign-in. Please sign in again later. (code 429)
login_code (guest)
Section titled “login_code (guest)”POST /api/guest/staff/login_code
Finishes a staff sign-in that waits for the authenticator app code.
| Parameter | Type | Description |
|---|---|---|
code |
string, required | The 6-digit code from the app, or the backup code. |
trust |
boolean | true to skip the second step in this browser for 30 days. |
Returns: An object with id, email, name and backup_used (true when the backup code was used; it is then gone). When two-factor sign-in was turned off while the sign-in waited and the email PIN is required: {"clientfence_pin": true}.
Errors:
- Your sign-in has expired. Please sign in again. (code 401)
- The code is not correct.
- Too many wrong codes. Please sign in again. (code 401)
- Too many wrong codes. Please try again later. (code 429)
- Check your login details (code 403)
A browser call in the same session as login: it needs POST, the CSRF token and a same-site origin.
login_code_email (guest)
Section titled “login_code_email (guest)”POST /api/guest/staff/login_code_email
For a staff sign-in that waits for the app code: emails a PIN instead, so either one finishes the sign-in.
No parameters.
Returns: true when a PIN was sent.
Errors:
- Your sign-in has expired. Please sign in again. (code 401)
login_pin_app (guest)
Section titled “login_pin_app (guest)”POST /api/guest/staff/login_pin_app
For a staff sign-in that waits for the email PIN: goes back to asking for the authenticator app code.
No parameters.
Returns: true
Errors:
- Your sign-in has expired. Please sign in again. (code 401)
- Two-factor sign-in is not on.
passkey_on (guest)
Section titled “passkey_on (guest)”POST /api/guest/staff/passkey_on
Says whether the staff sign-in page offers passkey sign-in.
No parameters.
Returns: true when passkeys are turned on for staff.
passkey_signin_options (guest)
Section titled “passkey_signin_options (guest)”POST /api/guest/staff/passkey_signin_options
Starts a passkey sign-in: returns the options for the browser’s navigator.credentials.get().
No parameters.
Returns: An object: challenge, rpId, userVerification (required) and timeout (milliseconds).
Errors:
- Passkey sign-in is not on.
passkey_signin (guest)
Section titled “passkey_signin (guest)”POST /api/guest/staff/passkey_signin
Signs a staff member in with a passkey, instead of the password and the second step. The IP address and country rules still apply.
| Parameter | Type | Description |
|---|---|---|
id |
string, required | The credential ID (base64url). |
clientDataJSON |
string, required | From the browser’s response (base64url). |
authenticatorData |
string, required | From the browser’s response (base64url). |
signature |
string, required | From the browser’s response (base64url). |
userHandle |
string | From the browser’s response (base64url). |
Returns: An object with id, email and name of the signed-in staff member.
Errors:
- Passkey sign-in is not on.
- This passkey is not set up for this sign-in. Please sign in with your password.
- The passkey could not be checked. Please try again, or sign in with your password.
- You are not allowed to login to admin area from this IP address. (code 403)
- Staff sign-in is not allowed from your location. (code 403)
- Check your login details (code 403)
A browser call in the same session as passkey_signin_options: it needs POST, the CSRF token and a same-site origin, and has the sign-in limit of 10 tries an hour per IP address.
update_password (guest)
Section titled “update_password (guest)”POST /api/guest/staff/update_password
Sets a new staff password from a password reset link, and signs the staff member out everywhere.
| Parameter | Type | Description |
|---|---|---|
code |
string, required | The code from the reset link (valid 15 minutes, once). |
password |
string, required | 8 to 256 characters, with a number, a lowercase and an uppercase letter. |
password_confirm |
string, required | The same password again. |
Returns: null (no value) when the password was changed.
Errors:
- Password reset has been disabled
- Code required / Password required / Password confirmation required
- Passwords do not match.
- The link has expired or you have already confirmed the password reset.
- Too many attempts: 20 a minute per IP address.
Emails the staff member that the password was changed. Fires onBeforePasswordResetStaff and onAfterPasswordResetStaff.
passwordreset (guest)
Section titled “passwordreset (guest)”POST /api/guest/staff/passwordreset
Emails a staff member a password reset link. To keep staff emails private, it returns true whether or not the email belongs to an active staff member.
| Parameter | Type | Description |
|---|---|---|
email |
string, required | The staff member’s email. |
g-recaptcha-response |
string | The CAPTCHA answer while a CAPTCHA is on (cf-turnstile-response or h-captcha-response for the other providers). |
Returns: true
Errors:
- Password reset has been disabled
- Email required
- You have to complete the CAPTCHA to continue (and the other CAPTCHA messages)
At most 5 requests an hour per IP address and 3 per email; requests over the limit return true and send nothing. See Staff password recovery.

