diff --git a/docs/docs/content/apis/apis.md b/docs/docs/content/apis/apis.md
index 4e6af46a..ad176149 100644
--- a/docs/docs/content/apis/apis.md
+++ b/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/)
+
diff --git a/docs/docs/content/apis/bounces.md b/docs/docs/content/apis/bounces.md
index 6c4568b9..bcc13305 100644
--- a/docs/docs/content/apis/bounces.md
+++ b/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"}'
 ```
diff --git a/docs/docs/content/apis/campaigns.md b/docs/docs/content/apis/campaigns.md
index ffa8faf6..06140e11 100644
--- a/docs/docs/content/apis/campaigns.md
+++ b/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
diff --git a/docs/docs/content/apis/import.md b/docs/docs/content/apis/import.md
index 4345e1ce..e565e6a5 100644
--- a/docs/docs/content/apis/import.md
+++ b/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
diff --git a/docs/docs/content/apis/lists.md b/docs/docs/content/apis/lists.md
index 4db39069..f8983724 100644
--- a/docs/docs/content/apis/lists.md
+++ b/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'
 ```
diff --git a/docs/docs/content/apis/media.md b/docs/docs/content/apis/media.md
index 3fffa082..144e843e 100644
--- a/docs/docs/content/apis/media.md
+++ b/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
diff --git a/docs/docs/content/apis/templates.md b/docs/docs/content/apis/templates.md
index 3984f186..0d2a0eb2 100644
--- a/docs/docs/content/apis/templates.md
+++ b/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
diff --git a/docs/docs/content/apis/transactional.md b/docs/docs/content/apis/transactional.md
index 130fa756..80207ec7 100644
--- a/docs/docs/content/apis/transactional.md
+++ b/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