From 2e8a5ace1d944e16afdaee8faa6fcb432c31a5f4 Mon Sep 17 00:00:00 2001 From: Kailash Nadh Date: Sun, 19 Jan 2025 11:19:56 +0530 Subject: [PATCH] Add user roles/perms documentation. Closes #2242. --- docs/docs/content/roles-and-permissions.md | 41 ++++++++++++++++++++++ docs/docs/mkdocs.yml | 1 + 2 files changed, 42 insertions(+) create mode 100644 docs/docs/content/roles-and-permissions.md diff --git a/docs/docs/content/roles-and-permissions.md b/docs/docs/content/roles-and-permissions.md new file mode 100644 index 000000000..5f17aa00b --- /dev/null +++ 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 index 0534eb601..32170a5fe 100644 --- 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