Skip to content

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.

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"
}
]
}
]
}

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

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.

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.

POST /api/admin/staff/is_super_administrator

Says whether the caller is a Super Administrator.

No parameters.

Returns: true or false.

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:

true

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.

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.

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:

7

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".

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.

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:

6

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

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

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:

true

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

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

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

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

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.

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

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"
}

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.

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)

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.

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)

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.

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.

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.

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.

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.

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.