Improve API auth/permission docs and examples.

docs/docs/content/apis/apis.md

@@ -2,13 +2,33 @@
 
 All features that are available on the listmonk dashboard are also available as REST-like HTTP APIs that can be interacted with directly. Request and response bodies are JSON. This allows easy scripting of listmonk and integration with other systems, for instance, synchronisation with external subscriber databases.
 
-API requests require BasicAuth authentication with the admin credentials.
+!!! note
+    If you come across API calls that are yet to be documented, please consider contributing to docs.
 
-> The API section is a work in progress. There may be API calls that are yet to be documented. Please consider contributing to docs.
 
-## OpenAPI (Swagger) spec
+## Auth
+HTTP API requests support BasicAuth and a Authorization `token` headers. API users and tokens with the required permissions can be created and managed on the admin UI (Admin -> Users).
 
-The auto-generated OpenAPI (Swagger) specification site for the APIs are available at [**listmonk.app/docs/swagger**](https://listmonk.app/docs/swagger/)
+##### BasicAuth example
+```shell
+curl -u "api_user:token" http://localhost:9000/api/lists
+```
+
+##### Authorization token example
+```shell
+curl -H "Authorization: token api_user:token" http://localhost:9000/api/lists
+```
+
+## Permissions
+**User role**: Permissions allowed for a user are defined as a *User role* (Admin -> User roles) and then attached to a user. 
+
+**List role**: Read / write permissions per-list can be defined as a *List role* (Admin -> User roles) and then attached to a user. 
+
+In a *User role*, `lists:get_all` or `lists:manage_all` permission supercede and override any list specific permissions for a user defined in a *List role*.
+
+To manage lists and subscriber list subscriptions via API requests, ensure that the appropriate permissions are attached to the API user.
+
+______________________________________________________________________
 
 ## Response structure
 
@@ -57,3 +77,9 @@ All timestamp fields are in the format `2019-01-01T09:00:00.000000+05:30`. The s
 |  502  | The backend OMS is down and the API is unable to communicate with it        |
 |  503  | Service unavailable; the API is down                                        |
 |  504  | Gateway timeout; the API is unreachable                                     |
+
+
+## OpenAPI (Swagger) spec
+
+The auto-generated OpenAPI (Swagger) specification site for the APIs are available at [**listmonk.app/docs/swagger**](https://listmonk.app/docs/swagger/)
+

docs/docs/content/apis/bounces.md

@@ -27,7 +27,7 @@ Retrieve the bounce records.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/bounces?campaign_id=1&page=1&per_page=2' \ 
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/bounces?campaign_id=1&page=1&per_page=2' \ 
     -H 'accept: application/json' -H 'Content-Type: application/x-www-form-urlencoded' \
     --data '{"source":"demo","order_by":"created_at","order":"asc"}'
 ```

docs/docs/content/apis/campaigns.md

@@ -23,7 +23,7 @@ Retrieve all campaigns.
 ##### Example Request
 
 ```shell
- curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns?page=1&per_page=100'
+ curl -u "api_user:token" -X GET 'http://localhost:9000/api/campaigns?page=1&per_page=100'
 ```
 
 ##### Parameters
@@ -98,7 +98,7 @@ Retrieve a specific campaign.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/campaigns/1'
 ```
 
 ##### Example Response
@@ -153,7 +153,7 @@ Preview a specific campaign.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1/preview'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/campaigns/1/preview'
 ```
 
 ##### Example Response
@@ -178,7 +178,7 @@ Retrieve stats of specified campaigns.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/running/stats?campaign_id=1'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/campaigns/running/stats?campaign_id=1'
 ```
 
 ##### Example Response
@@ -208,7 +208,7 @@ Retrieve stats of specified campaigns.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/analytics/views?id=1&from=2024-08-04&to=2024-08-12'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/campaigns/analytics/views?id=1&from=2024-08-04&to=2024-08-12'
 ```
 
 ##### Example Response
@@ -248,7 +248,7 @@ curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/analytic
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/analytics/links?id=1&from=2024-08-04T18%3A30%3A00.624Z&to=2024-08-12T18%3A29%3A00.624Z'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/campaigns/analytics/links?id=1&from=2024-08-04T18%3A30%3A00.624Z&to=2024-08-12T18%3A29%3A00.624Z'
 ```
 
 ##### Example Response
@@ -303,7 +303,7 @@ Create a new campaign.
 ##### Example request
 
 ```shell
-curl -u "username:password" 'http://localhost:9000/api/campaigns' -X POST -H 'Content-Type: application/json;charset=utf-8' --data-raw '{"name":"Test campaign","subject":"Hello, world","lists":[1],"from_email":"listmonk <noreply@listmonk.yoursite.com>","content_type":"richtext","messenger":"email","type":"regular","tags":["test"],"template_id":1}'
+curl -u "api_user:token" 'http://localhost:9000/api/campaigns' -X POST -H 'Content-Type: application/json;charset=utf-8' --data-raw '{"name":"Test campaign","subject":"Hello, world","lists":[1],"from_email":"listmonk <noreply@listmonk.yoursite.com>","content_type":"richtext","messenger":"email","type":"regular","tags":["test"],"template_id":1}'
 ```
 
 ##### Example response
@@ -394,7 +394,7 @@ Change status of a campaign.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X PUT 'http://localhost:9000/api/campaigns/1/status' \
+curl -u "api_user:token" -X PUT 'http://localhost:9000/api/campaigns/1/status' \
 --header 'Content-Type: application/json' \
 --data-raw '{"status":"scheduled"}'
 ```
@@ -457,7 +457,7 @@ Publish campaign to public archive.
 
 ```shell
 
-curl -u "username:password" -X PUT 'http://localhost:8080/api/campaigns/33/archive' 
+curl -u "api_user:token" -X PUT 'http://localhost:8080/api/campaigns/33/archive' 
 --header 'Content-Type: application/json' 
 --data-raw '{"archive":true,"archive_template_id":1,"archive_meta":{},"archive_slug":"my-newsletter-old-edition"}'
 ```
@@ -490,7 +490,7 @@ Delete a campaign.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X DELETE 'http://localhost:9000/api/campaigns/34'
+curl -u "api_user:token" -X DELETE 'http://localhost:9000/api/campaigns/34'
 ```
 
 ##### Example Response

docs/docs/content/apis/import.md

@@ -16,7 +16,7 @@ Retrieve the status of an ongoing import.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/import/subscribers'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/import/subscribers'
 ```
 
 ##### Example Response
@@ -41,7 +41,7 @@ Retrieve logs from an ongoing import.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/import/subscribers/logs'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/import/subscribers/logs'
 ```
 
 ##### Example Response
@@ -77,7 +77,7 @@ Send a CSV (optionally ZIP compressed) file to import subscribers. Use a multipa
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X POST 'http://localhost:9000/api/import/subscribers' \
+curl -u "api_user:token" -X POST 'http://localhost:9000/api/import/subscribers' \
   -F 'params={"mode":"subscribe", "subscription_status":"confirmed", "delim":",", "lists":[1, 2], "overwrite": true}' \
   -F "file=@/path/to/subs.csv"
 ```
@@ -102,7 +102,7 @@ Stop and delete an ongoing import.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X DELETE 'http://localhost:9000/api/import/subscribers' 
+curl -u "api_user:token" -X DELETE 'http://localhost:9000/api/import/subscribers' 
 ```
 
 ##### Example Response

docs/docs/content/apis/lists.md

@@ -30,7 +30,7 @@ Retrieve lists.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/lists?page=1&per_page=100'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/lists?page=1&per_page=100'
 ```
 
 ##### Example Response
@@ -108,7 +108,7 @@ Retrieve a specific list.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/lists/5'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/lists/5'
 ```
 
 ##### Example Response
@@ -148,7 +148,7 @@ Create a new list.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X POST 'http://localhost:9000/api/lists'
+curl -u "api_user:token" -X POST 'http://localhost:9000/api/lists'
 ```
 
 ##### Example Response
@@ -190,7 +190,7 @@ Update a list.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X PUT 'http://localhost:9000/api/lists/5' \
+curl -u "api_user:token" -X PUT 'http://localhost:9000/api/lists/5' \
 --form 'name=modified test list' \
 --form 'type=private'
 ```

docs/docs/content/apis/media.md

@@ -16,7 +16,7 @@ Get an uploaded media file.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/media' \
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/media' \
 --header 'Content-Type: multipart/form-data; boundary=--------------------------093715978792575906250298'
 ```
 
@@ -87,7 +87,7 @@ Upload a media file.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X POST 'http://localhost:9000/api/media' \
+curl -u "api_user:token" -X POST 'http://localhost:9000/api/media' \
 --header 'Content-Type: multipart/form-data; boundary=--------------------------183679989870526937212428' \
 --form 'file=@/path/to/image.jpg'
 ```
@@ -122,7 +122,7 @@ Delete an uploaded media file.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X DELETE 'http://localhost:9000/api/media/1'
+curl -u "api_user:token" -X DELETE 'http://localhost:9000/api/media/1'
 ```
 
 ##### Example Response

docs/docs/content/apis/templates.md

@@ -20,7 +20,7 @@ Retrieve all templates.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/templates'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/templates'
 ```
 
 ##### Example Response
@@ -56,7 +56,7 @@ Retrieve a specific template.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/templates/1'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/templates/1'
 ```
 
 ##### Example Response
@@ -90,7 +90,7 @@ Retrieve the HTML preview of a template.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X GET 'http://localhost:9000/api/templates/1/preview'
+curl -u "api_user:token" -X GET 'http://localhost:9000/api/templates/1/preview'
 ```
 
 ##### Example Response
@@ -128,7 +128,7 @@ Create a template.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X POST 'http://localhost:9000/api/templates' \
+curl -u "api_user:token" -X POST 'http://localhost:9000/api/templates' \
 -H 'Content-Type: application/json' \
 -d '{
     "name": "New template",
@@ -179,7 +179,7 @@ Set a template as the default.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X PUT 'http://localhost:9000/api/templates/1/default'
+curl -u "api_user:token" -X PUT 'http://localhost:9000/api/templates/1/default'
 ```
 
 ##### Example Response
@@ -213,7 +213,7 @@ Delete a template.
 ##### Example Request
 
 ```shell
-curl -u "username:password" -X DELETE 'http://localhost:9000/api/templates/35'
+curl -u "api_user:token" -X DELETE 'http://localhost:9000/api/templates/35'
 ```
 
 ##### Example Response

docs/docs/content/apis/transactional.md

@@ -28,7 +28,7 @@ Allows sending transactional messages to one or more subscribers via a preconfig
 ##### Example
 
 ```shell
-curl -u "username:password" "http://localhost:9000/api/tx" -X POST \
+curl -u "api_user:token" "http://localhost:9000/api/tx" -X POST \
      -H 'Content-Type: application/json; charset=utf-8' \
      --data-binary @- << EOF
     {
@@ -55,7 +55,7 @@ ______________________________________________________________________
 To include file attachments in a transactional message, use the `multipart/form-data` Content-Type. Use `data` param for the parameters described above as a JSON object. Include any number of attachments via the `file` param.
 
 ```shell
-curl -u "username:password" "http://localhost:9000/api/tx" -X POST \
+curl -u "api_user:token" "http://localhost:9000/api/tx" -X POST \
 -F 'data=\"{
     \"subscriber_email\": \"user@test.com\",
     \"template_id\": 4