From: Stephen Finucane <stephen@that.guru>
Date: Fri, 9 Jun 2017 17:18:38 +0000 (+0100)
Subject: docs: Document token auth support
X-Git-Tag: v2.0.0-rc4^0
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=09b821a95ef74c7580b79c655cf782ad9ca7d081;p=thirdparty%2Fpatchwork.git

docs: Document token auth support

Signed-off-by: Stephen Finucane <stephen@that.guru>
Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com>
---

diff --git a/docs/api/rest.rst b/docs/api/rest.rst
index 8c8fd959..3d7292ef 100644
--- a/docs/api/rest.rst
+++ b/docs/api/rest.rst
@@ -161,14 +161,29 @@ parameters should be passed as form-encoded data:
 Authentication
 --------------
 
-Patchwork only supports basic authentication:
+Patchwork supports authentication using your username and password (basic
+authentication) or with a token (token authentication). The latter is
+recommended.
+
+To authenticate with token authentication, you must first obtain a token. This
+can be done from your profile, e.g. https://patchwork.example.com/profile.
+Once you have a token, run:
+
+.. code-block:: shell
+
+    $ curl -H "Authorization: Token ${token}" \
+        'https://patchwork.example.com/api/'
+
+To authenticate using basic auth, you should use your Patchwork username and
+password. To do this, run:
 
 .. code-block:: shell
 
-    $ curl -u username:password 'https://patchwork.example.com/api/'
+    $ curl -u ${username}:${password} \
+        'https://patchwork.example.com/api/'
 
-Not all resources require authentication. Those that do will return ``404 Not
-Found`` if authentication is not provided to avoid leaking information.
+Not all resources require authentication. Those that do will return ``404 (Not
+Found)`` if authentication is not provided to avoid leaking information.
 
 Pagination
 ----------