API: Managing roles
Available since FileRun 2026.3.0.
All the endpoints below require the admin scope, take POST requests and answer with JSON.
| Action | Target URL |
|---|---|
| Get role information | /api.php/Core/!admin/roles/info |
| Add a role | /api.php/Core/!admin/roles/add |
| Edit a role | /api.php/Core/!admin/roles/edit |
| Delete a role | /api.php/Core/!admin/roles/delete |
Who can manage roles
- The superuser manages every role.
- An independent administrator manages the roles they own (the roles they created).
- A simple administrator needs the permission to manage roles. They cannot manage roles while a home folder template path is set for their account, and they cannot manage the role assigned to their own account.
- Only the superuser can set the administrative permissions of a role (
admin_type,admin_overand the otheradmin_*permissions). Sent by any other administrator, they are ignored. - An administrator with a home folder template path of their own cannot set
drive_homefolder_template. Sent by them, it is ignored.
Getting role information
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | The role id |
The response carries the role in data, every value named the way the add and edit endpoints take it, so a role can be read, changed and sent back: id, system (1 for the predefined Guest role), owner, name, description, drive_homefolder_template and the permissions listed below. The users_may_see and admin_over selections are returned in the form they are submitted in (-ALL-, or group:1|group:2|user:3).
For older clients, the response also carries the names of FileRun 2026.3: homefolder, with the value of drive_homefolder_template, and changes and readonly. changes is 1 when the role has all three of rename_move, delete_files and delete_folders, and 0 otherwise. readonly is the opposite.
Adding a role
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Unique among the roles of the same owner |
| description | string | No | |
| drive_homefolder_template | string | No | The home folder assigned to the accounts holding the role. An absolute server path. Always use forward slashes as separators. Named homefolder before FileRun 2026.4.0, which is still accepted when drive_homefolder_template is not sent. |
| perms[...] | No | The permissions, see below. A permission left out is stored as 0. |
The response carries the id of the new role as data.rid.
Editing a role
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | The role id |
| name | string | No | |
| description | string | No | |
| drive_homefolder_template | string | No | |
| perms[...] | No | The permissions, see below |
Only what is sent is written. A parameter or a permission left out leaves the role as it is, so one value can be changed without sending the whole role. A request which changes nothing is refused with "No changes were made!". Changing drive_homefolder_template updates the home folder of every account holding the role. As for adding, homefolder is accepted in its place.
The predefined Guest role can be edited, with two limits: its name and description cannot be changed, and the permissions which are fixed for guest accounts keep their fixed values, whatever the request sends. Since FileRun 2026.4.0, edit_files, collections and starring are not among the fixed ones: the Guest role can allow guests to edit files, use collections and star items.
Deleting a role
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | The role id |
A role assigned to at least one account cannot be deleted ("You cannot delete this role because it is assigned to 1 users."). The predefined Guest role cannot be deleted. Neither can a role which an authentication source gives to the accounts it creates, whether the source is enabled or not ("This role is currently being assigned to newly authenticated users and cannot be deleted!").
The permissions
| Parameter | Type | Description |
|---|---|---|
| perms[admin_type] | string | simple, indep, or empty for no administrative permissions. Superuser only. |
| perms[admin_over] | string | -ALL-, or the groups the administrator manages, as group:1|group:2. Superuser only. |
| perms[admin_max_users] | integer | Superuser only. |
| perms[admin_max_guest_users] | integer | Empty for no limit. Superuser only. |
| perms[admin_homefolder_template] | string | Superuser only. |
| perms[admin_users] | boolean (1/0) | Superuser only. |
| perms[admin_roles] | boolean (1/0) | Superuser only. |
| perms[admin_notifications] | boolean (1/0) | Superuser only. |
| perms[admin_logs] | boolean (1/0) | Superuser only. |
| perms[admin_metadata] | boolean (1/0) | Superuser only. |
| perms[admin_shared_drives] | boolean (1/0) | Since 2026.4.0. Lets a simple administrator administer the shared drives. Superuser only. |
| perms[upload] | boolean (1/0) | |
| perms[upload_max_size] | integer | 0 for no limit |
| perms[upload_limit_types] | string | Comma delimited list of file extensions |
| perms[download] | boolean (1/0) | |
| perms[download_folders] | boolean (1/0) | |
| perms[edit_files] | boolean (1/0) | Since 2026.4.0. Edit existing files, including managing their previous versions. |
| perms[rename_move] | boolean (1/0) | Since 2026.4.0. Rename and move files and folders. |
| perms[delete_files] | boolean (1/0) | Since 2026.4.0. Delete files, open the trash and restore items from it. |
| perms[delete_folders] | boolean (1/0) | Since 2026.4.0. Delete folders. |
| perms[delete_permanently] | boolean (1/0) | Since 2026.4.0. Delete files and folders permanently and empty the trash. |
| perms[collections] | boolean (1/0) | Since 2026.4.0. Create and manage collections and photo albums. |
| perms[starring] | boolean (1/0) | Since 2026.4.0. Star files and folders. |
| perms[changes] | boolean (1/0) | The permission of FileRun 2026.3, still accepted for older clients. It sets rename_move, delete_files, delete_folders and delete_permanently to its value, except the ones the request sends itself. |
| perms[read_comments] | boolean (1/0) | |
| perms[write_comments] | boolean (1/0) | |
| perms[weblink] | boolean (1/0) | |
| perms[share] | boolean (1/0) | |
| perms[share_guests] | boolean (1/0) | |
| perms[metadata] | boolean (1/0) | |
| perms[write_metadata] | boolean (1/0) | Since 2026.4.0. Change tags, ratings and other metadata. |
| perms[file_history] | boolean (1/0) | |
| perms[change_auth] | boolean (1/0) | Whether the users may change their password and sign-in methods |
| perms[edit_profile] | boolean (1/0) | |
| perms[users_may_see] | string | -ALL-, or the groups and users the role may see, as group:1|group:2|user:3 |
| perms[space_quota_max] | integer | In MB. 0 for no quota. |
As for accounts, a permission which means nothing without another one is stored as 0 when that one is 0, as listed on Add FileRun user accounts. Without download, for example, a role has none of the permissions which act on files. On an edit, the rule is applied to the role as it will stand, so turning download off also turns off the permissions which depend on it.