docs: describe the create capability and management section access rules

Documents that create is granted independently of the access level, which levels
already include it, and the single rule that decides whether /manage/apps and
/manage/integrations are reachable and what each shows.
This commit is contained in:
Thomas Camlong committed 2026-08-18 15:40:29 +02:00
1 parent 3bbe7f2a98
commit 78da525883
3 files changed
+80 -41

No files matched your search

+13 -2
View File
@@ -51,6 +51,17 @@ Note that the ping URL only accepts `http://` and `https://` URLs — custom URI
## List of apps
On the apps management page you find all apps that exist in your Homarr instance. Search by name or URL, open an app directly, or use its row actions to edit and delete it. A filtered search can be cleared without leaving the page.
On the apps management page you find all apps that exist in your Homarr instance. Search by name or URL, open an app
directly, or use its row actions to edit and delete it. A filtered search can be cleared without leaving the page.
Viewing this list requires the `app-modify-all` permission. Creating an app requires `app-create`, editing requires `app-modify-all`, and deleting requires `app-full-all`; board permissions are not required.
### Accessing the page
The `/manage/apps` page is reachable when you can manage all apps (`app-modify-all`) or create apps (`app-create`):
- **Manage all (`app-modify-all`)**: the full list of apps is shown and searchable, and each row can be edited.
- **Create only (`app-create`)**: the page shows an empty "create an app" state instead of the list, so the names and
URLs of existing apps are never disclosed. The create action is still available.
- **Neither**: the page is not reachable and returns a not-found page.
Creating an app requires `app-create`, editing requires `app-modify-all`, and deleting requires `app-full-all`;
board permissions are not required.
@@ -17,7 +17,23 @@ To create an integration, choose **New integration** and select the supported ap
The integrations management page uses a searchable list. Each row shows the integration type and URL, with the actions you have permission to use.
This page is only visible to users with the global `integration-full-all` permission or with full access on at least one integration. Without the global permission, only the integrations you have full access to are shown.
### Accessing the page
The `/manage/integrations` page is reachable when at least one of the following applies:
- you can manage all integrations (global `integration-full-all`),
- you can create integrations (`integration-create`), or
- you have been granted full access to at least one specific integration.
What the page shows depends on the case:
- **Manage all (`integration-full-all`)**: the full list of integrations is shown.
- **Create only (`integration-create`)**: the page shows an empty "create an integration" state instead of the list, with the create action still available.
- **Delegated (full access on one or more)**: only the integrations you have full access to are listed, above a note making clear that the view is scoped to what you can manage.
- **None**: the page is not reachable and returns a not-found page.
Where you have a mix of access, the list combines the integrations you can manage. Integration lists are filtered
server side, so a user never receives data about integrations they lack access to.
Next, you'll need to fill out the required fields to configure the integration:
+50 -38
View File
@@ -163,59 +163,71 @@ Members can be removed from the group using the remove button at the end:
#### Permissions tab
In this tab, you manage what permissions the members of this group will have.
Permissions are organized by category (boards, apps, integrations, and so on). Each category is a row with a
segmented control that lets you pick a single access level. Selecting a level grants that level and every lower
level in the same category. Choosing **None** removes all permissions for that category.
Permissions are shown as a matrix with one row per category (boards, apps, integrations, and so on). Each row has a
segmented control that lets you pick a single **access level** and, where the category supports it, a separate
**create** checkbox.
Selecting **Administrator** grants full access to everything. While the administrator level is selected, every
other category is disabled and shows a **Granted via Administrator** caption, because administrators already have
all permissions. Deselecting it (choosing **None** on the administrator row) re-enables the other categories.
Levels in a category are cumulative: selecting a level grants that level and every level below it in the same
category. Choosing **No access** grants no access level for that category.
##### Create is separate from the access level
Creating is a distinct capability, independent of the access level. It can be granted on its own, so you can for
example let members create their own boards without letting them view or modify anyone else's boards. Some access
levels already include the create capability through permission inheritance (marked in the table below); the
checkbox is then disabled and labeled as already included.
##### Administration
Selecting the **Administrator** level grants full access to everything. While it is selected, every other category
is disabled and explains that administrators already have that access. Setting the administrator row back to
**No access** re-enables the other categories with the selections they had before.
##### Access levels
The access levels below are cumulative, in ascending order, with the category's create capability listed separately.
A level that already includes the create capability is marked:
| Category | Create capability | Access levels (ascending) | Create included at |
| -------------- | --------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Boards | Create boards | view all boards → modify all boards → full board access | full board access |
| Apps | Create apps | use all apps → modify all apps → full app access | modify all apps, full app access |
| Integrations | Create integrations | use all integrations → interact with any integration → full integration access | full integration access |
| Search engines | Create search engines | modify all search engines → full search engine access | modify all search engines, full search engine access |
| Medias | Upload medias | view all medias → full media access | full media access |
| Other | — | view logs | — |
| Administrator | — | administrator | — |
The levels grant the following:
- **Boards**: view all boards; modify all boards (not access control and danger zone); full board access (view, modify and delete every board, including access control and the danger zone).
- **Apps**: use all apps (add any app to a board); modify all apps; full app access (manage, use and delete any app).
- **Integrations**: use all integrations; interact with any integration; full integration access (manage, use and interact with any integration).
- **Search engines**: modify all search engines; full search engine access (manage and delete any search engine).
- **Medias**: view all medias; full media access (manage and delete any media).
- **Other**: view logs.
##### Presets
Above the rows you can apply a preset to fill in a common configuration in one click:
- **Viewer**: view access to boards, use access to apps and integrations, and viewing media.
- **Editor**: modify access to boards and apps, interact with integrations, modify search engines (includes creating), and viewing media.
- **Viewer**: read-only - view boards and medias, use existing apps and integrations.
- **Editor**: day-to-day management - create and modify boards, apps, integrations and search engines, interact with integrations, and upload medias, without deleting resources or managing access.
- **Admin**: grants the administrator permission (full access to everything).
When the current selection does not match any preset, a **Custom** badge is shown.
##### Implied permissions
##### Also grants
Some levels include additional permissions automatically. When a level implies extra permissions (for example,
full board access also allows creating boards), a dimmed `also grants: …` hint is shown under the category row.
full board access also allows creating boards), a dimmed **Also grants: …** hint is shown below the category row,
listing the implied permissions.
##### Effective permissions
Below the rows, the **Effective permissions** panel can be expanded to review everything members of this group
will be able to do, including implied permissions, grouped by category with a count for each.
Each category below is a segmented control that starts with **None**; the remaining segments are the access levels
in ascending order (higher levels include the lower ones and may imply extra permissions shown in the hint):
- Boards — None
- **View all boards**: Allow members to view all boards
- **Modify all boards**: Allow members to modify all boards (Does not include access control and danger zone)
- **Full board access**: Allow members to view, modify, and delete all boards (Including access control and danger zone; includes creating boards)
- Apps — None
- **Use all apps**: Allow members to add any apps to their boards
- **Modify all apps**: Allow members to modify all apps (includes creating apps)
- **Full app access**: Allow members to manage, use and delete any app
- Integrations — None
- **Use all integrations**: Allow members to add any integrations to their boards
- **Interact with any integration**: Allow members to interact with any integration
- **Full integration access**: Allow members to manage, use and interact with any integration (includes creating integrations)
- Search engines — None
- **Modify all search engines**: Allow members to modify all search engines (includes creating search engines)
- **Full search engine access**: Allow members to manage and delete any search engine
- Medias — None
- **View all medias**: Allow members to view all medias
- **Full media access**: Allow members to manage and delete any media (includes uploading medias)
- Other — None
- **View logs**: Allow members to view logs
- Administrator — None
- **Administrator**: Members with this permission have full access to all features and settings
Below the rows, the **Effective permissions** panel can be expanded to review everything members of this group will
be able to do - the full, de-duplicated set of permissions, including everything granted indirectly through the
levels - grouped by category, with a count for each.
Custom Widget authoring, import, migration, preview, secrets, Workshop access, and placement configuration are reserved
for administrators and are not separate assignable group permissions. Board modifiers can still move, resize, change