Add user roles/perms documentation. Closes #2242.

knadh · Jan 19, 2025 · 2e8a5ac · 2e8a5ac
1 parent 0930a22
commit 2e8a5ac
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 0 deletions.
diff --git a/docs/docs/content/roles-and-permissions.md b/docs/docs/content/roles-and-permissions.md
@@ -0,0 +1,41 @@
+listmonk supports (>= v4.0.0) creating systems users with granular permissions to various features, including list-specific permissions. Users can login with a username and password, or via an OIDC (OpenID Connect) handshake if an auth provider is connected. Various permissions can be grouped into "user roles", which can be assigned to users. List-specific permissions can be grouped into "list roles".
+
+## User roles
+
+A user role is a collection of user related permissions. User roles are attached to user accounts. User roles can be managed in `Admin -> Users -> User roles` The permissions are described below.
+
+| Group       | Permission              | Description                                                                                                                                                                                                                          |
+| ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| lists       | lists:get_all           | Get details of all lists                                                                                                                                                                                                                |
+|             | lists:manage_all        | Create, update, and delete all lists                                                                                                                                                                                                 |
+| subscribers | subscribers:get         | Get individual subscriber details                                                                                                                                                                                                    |
+|             | subscribers:get_all     | Get all subscribers and their details                                                                                                                                                                                                |
+|             | subscribers:manage      | Add, update, and delete subscribers                                                                                                                                                                                                  |
+|             | subscribers:import      | Import subscribers from external files                                                                                                                                                                                               |
+|             | subscribers:sql_query   | Run SQL queries on subscriber data. **WARNING:** This permission will allow the querying of all lists and subscribers directly from the database with SQL expressions, superceding individual list and subscriber permissions above. |
+|             | tx:send                 | Send transactional messages to subscribers                                                                                                                                                                                           |
+| campaigns   | campaigns:get           | Get campaign details                                                                                                                                                                                                                 |
+|             | campaigns:get_analytics | Access campaign performance metrics                                                                                                                                                                                                  |
+|             | campaigns:manage        | Create, update, and delete campaigns                                                                                                                                                                                                 |
+| bounces     | bounces:get             | Get email bounce records                                                                                                                                                                                                             |
+|             | bounces:manage          | Process and handle bounced emails                                                                                                                                                                                                    |
+|             | webhooks:post_bounce    | Receive bounce notifications via webhook                                                                                                                                                                                             |
+| media       | media:get               | Get uploaded media files                                                                                                                                                                                                             |
+|             | media:manage            | Upload, update, and delete media                                                                                                                                                                                                     |
+| templates   | templates:get           | Get email templates                                                                                                                                                                                                                  |
+|             | templates:manage        | Create, update, and delete templates                                                                                                                                                                                                 |
+| users       | users:get               | Get system user accounts                                                                                                                                                                                                             |
+|             | users:manage            | Create, update, and delete user accounts                                                                                                                                                                                             |
+|             | roles:get               | Get user roles and permissions                                                                                                                                                                                                       |
+|             | roles:manage            | Create and modify user roles                                                                                                                                                                                                         |
+| settings    | settings:get            | Get system settings                                                                                                                                                                                                                  |
+|             | settings:manage         | Modify system configuration                                                                                                                                                                                                          |
+|             | settings:maintain       | Perform system maintenance tasks                                                                                                                                                                                                     |
+
+## List roles
+
+A list role is a collection of permissions assigned per list. Each list can be assigned a view (read) or manage (update) permission. List roles are attached to user accounts. Only the lists defined in a list role is accessible by the user, be it on the admin UI or via API calls. Do note that the `lists:get_all` and `lists:manage_all` permissions in user roles override all per-list permissions.
+
+## API users
+
+A user account can be of two types, a regular user or an API user. API users are meant for intertacting with the listmonk APIs programmatically. Unlike regular user accounts that have custom passwords or OIDC for authentication, API users get an automatically generated secret token.
diff --git a/docs/docs/mkdocs.yml b/docs/docs/mkdocs.yml
@@ -53,6 +53,7 @@ nav:
     - "Archives": "archives.md"
     - "Internationalization": "i18n.md"
     - "Integrating with external systems": external-integration.md
+    - "User roles and permissions": roles-and-permissions.md
   - "API":
     - "Introduction": apis/apis.md
     - "SDKs and libs": apis/sdks.md