From 5333ee76baa44bcb60f61e5858b3e9da439b2f59 Mon Sep 17 00:00:00 2001
From: dogeystamp <dogeystamp@disroot.org>
Date: Wed, 14 Jun 2023 22:12:40 -0400
Subject: [PATCH] /whoami: added docs

---
 TODO.txt             |  2 +-
 docs/permissions.rst | 18 ++++++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/TODO.txt b/TODO.txt
index d5cc6cb..7ff4b15 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -247,7 +247,7 @@
 
 [-] implement /whoami endpoint
 	[ ] tests
-	[ ] docs
+	[x] docs
 
 [ ] investigate cleanup being in the user subcmd
 [ ] investigate cleanup cmd triggering foreign key failure
diff --git a/docs/permissions.rst b/docs/permissions.rst
index dcece3f..be68f88 100644
--- a/docs/permissions.rst
+++ b/docs/permissions.rst
@@ -4,6 +4,8 @@ Permissions
 Sachet offers a selection of permissions that can be assigned to users,
 which manage their access to certain endpoints.
 
+.. _permissions_serialization:
+
 Serialization
 -------------
 In Sachet's JSON API, permissions are serialized as an array of string codes.
@@ -59,3 +61,19 @@ The following is a table of permissions Sachet offers, and what they do:
     * - Administration
       - ``ADMIN``
       - Allows creating users and managing their permissions.
+
+Whoami API
+----------
+
+Information about the current user and their permissions can be obtained through this API.
+``GET /whoami`` will return a result like this:
+
+.. code-block:: json
+
+    {
+        "username": "user",
+        "permissions": ["READ", "CREATE"]
+    }
+
+``permissions`` will be serialized as in :ref:`permissions_serialization`.
+If the user is not currently signed in, ``username`` will be ``null``.