From 1c9766b8fd31a23864a467aab2af0c5fc1cae964 Mon Sep 17 00:00:00 2001
From: Philipp Heckel <pheckel@datto.com>
Date: Thu, 3 Feb 2022 13:40:19 -0500
Subject: [PATCH] More docs

---
 docs/config.md  |  6 ++--
 docs/publish.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+), 3 deletions(-)

diff --git a/docs/config.md b/docs/config.md
index 54f9627a..2bc19884 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -131,7 +131,8 @@ Access control entries can be applied to users as well as the special everyone u
 
 To set up auth, simply **configure the following two options**:
 
-* `auth-file` is the user/access database; it is created automatically if it doesn't already exist
+* `auth-file` is the user/access database; it is created automatically if it doesn't already exist; suggested 
+  location `/var/lib/ntfy/user.db` (easiest if deb/rpm package is used)
 * `auth-default-access` defines the default/fallback access if no access control entry is found; it can be
   set to `read-write` (default), `read-only`, `write-only` or `deny-all`.
 
@@ -166,8 +167,7 @@ ntfy user change-role phil admin   # Make user phil an admin
 The access control list (ACL) **manages access to topics for non-admin users, and for anonymous access**. Each entry 
 represents the access permissions for a user to a specific topic or topic pattern. 
 
-**Modifying the ACL:**   
-The access control list can be displayed or modified with the `ntfy access` command:
+The ACL can be displayed or modified with the `ntfy access` command:
 
 ```
 ntfy access                            # Shows the entire access control list
diff --git a/docs/publish.md b/docs/publish.md
index 92c27f67..170b70ad 100644
--- a/docs/publish.md
+++ b/docs/publish.md
@@ -941,6 +941,81 @@ title `You've Got Mail` to topic `sometopic` (see [ntfy.sh/sometopic](https://nt
 
 ## Advanced features
 
+### Authentication
+Depending on whether the server is configured to support [access control](config.md#access-control), some topics
+may be read/write protected so that only users with the correct credentials can subscribe or publish to them.
+To publish/subscribe to protected topics, you can use [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication)
+with a valid username/password. For your self-hosted server, **be sure to use HTTPS to avoid eavesdropping** and exposing
+your password. 
+
+Here's a simple example:
+
+=== "Command line (curl)"
+    ```
+    curl \
+      -u phil:mypass \
+      -d "Look ma, with auth" \
+      https://ntfy.example.com/mysecrets
+    ```
+
+=== "ntfy CLI"
+    ```
+    ntfy publish \
+      -u phil:mypass \
+      ntfy.example.com/mysecrets \
+      "Look ma, with auth"
+    ```
+
+=== "HTTP"
+    ``` http
+    POST /mysecrets HTTP/1.1
+    Host: ntfy.example.com
+    Authorization: Basic cGhpbDpteXBhc3M=
+
+    Look ma, with auth
+    ```
+
+=== "JavaScript"
+    ``` javascript
+    fetch('https://ntfy.example.com/mysecrets', {
+        method: 'POST', // PUT works too
+        body: 'Look ma, with auth',
+        headers: {
+            'Authorization': 'Basic cGhpbDpteXBhc3M='
+        }
+    })
+    ```
+
+=== "Go"
+    ``` go
+    req, _ := http.NewRequest("POST", "https://ntfy.example.com/mysecrets",
+    strings.NewReader("Look ma, with auth"))
+    req.Header.Set("Authorization", "Basic cGhpbDpteXBhc3M=")
+    http.DefaultClient.Do(req)
+    ```
+
+=== "Python"
+    ``` python
+    requests.post("https://ntfy.example.com/mysecrets",
+    data="Look ma, with auth",
+    headers={
+        "Authorization": "Basic cGhpbDpteXBhc3M="
+    })
+    ```
+
+=== "PHP"
+    ``` php-inline
+    file_get_contents('https://ntfy.example.com/mysecrets', false, stream_context_create([
+        'http' => [
+            'method' => 'POST', // PUT also works
+            'header' =>
+                'Content-Type: text/plain\r\n' .
+                'Authorization: Basic cGhpbDpteXBhc3M=',
+            'content' => 'Look ma, with auth'
+        ]
+    ]));
+    ```
+
 ### Message caching
 !!! info
     If `Cache: no` is used, messages will only be delivered to connected subscribers, and won't be re-delivered if a 
@@ -1133,3 +1208,4 @@ and can be passed as **HTTP headers** or **query parameters in the URL**. They a
 | `X-Cache`       | `Cache`                                    | Allows disabling [message caching](#message-caching)                                          |
 | `X-Firebase`    | `Firebase`                                 | Allows disabling [sending to Firebase](#disable-firebase)                                     |
 | `X-UnifiedPush` | `UnifiedPush`, `up`                        | [UnifiedPush](#unifiedpush) publish option, only to be used by UnifiedPush apps               |
+| `Authorization` | -                                          | If supported by the server, you can [login to access](#authentication) protected topics       |