From ad8e9609b2bc512c5ea373d8d0ed07868215120c Mon Sep 17 00:00:00 2001
From: Vahid Al <thevahidal@gmail.com>
Date: Mon, 3 Jun 2024 19:43:37 +0330
Subject: [PATCH] Add examples for auth endpoints

---
 docs/api-examples.md      |   3 +-
 docs/api/auth-examples.md | 164 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 166 insertions(+), 1 deletion(-)
 create mode 100644 docs/api/auth-examples.md

diff --git a/docs/api-examples.md b/docs/api-examples.md
index edfe08d..e0a76e6 100644
--- a/docs/api-examples.md
+++ b/docs/api-examples.md
@@ -35,7 +35,8 @@ soul -d ./Chinook_Sqlite.sqlite -p 8000
 
 1. [/api/tables](api/tables-examples.md) Examples for Tables endpoints
 2. [/api/rows](api/rows-examples.md) Examples for Rows endpoints
-3. [/api/](api/root-examples.md) Examples for Root endpoints
+3. [/api/auth/](api/auth-examples.md) Examples for Authentication / Authorization endpoints
+4. [/api/](api/root-examples.md) Examples for Root endpoints
 
 ## Handling Errors
 
diff --git a/docs/api/auth-examples.md b/docs/api/auth-examples.md
new file mode 100644
index 0000000..4e12f7b
--- /dev/null
+++ b/docs/api/auth-examples.md
@@ -0,0 +1,164 @@
+## Authentication / Authorization
+
+These endpoints are for Soul in the Auth mode. For that you need to enable auth mode by setting the `AUTH=true` environment variable or using the `-a` argument when starting a Soul server.
+
+### 1. Obtain an access token
+
+To obtain an access token call `/auth/token/obtain/` endpoint with `POST` method.
+
+```bash
+curl -v --request POST \
+  --url http://localhost:8000/api/auth/token/obtain \
+  --header 'Content-Type: application/json' \
+  --data '{
+	"fields": {
+		"username": "damien",
+		"password": "strongpass"
+	}
+}'
+```
+
+Response
+
+```
+...
+< Set-Cookie: accessToken=<jwt-access-token>; Path=/; HttpOnly
+< Set-Cookie: refreshToken=<jwt-refresh-token>; Path=/; HttpOnly
+...
+```
+
+> You can see that when login is successful, Soul sets two cookies one for the access token and the other for the refresh token.
+
+```json
+{
+  "message": "Success",
+  "data": {
+    "userId": 1
+  }
+}
+```
+
+#### Body Params
+
+- `fields` containing `username` and `password` e.g.
+
+```json
+"fields": {
+		"username": "damien",
+		"password": "strongpass"
+}
+```
+
+> Here's how the jwt access token payload looks like:
+
+```json
+{
+  "subject": "accessToken",
+  "username": "damien",
+  "userId": 1,
+  "isSuperuser": "false",
+  "roleIds": [1],
+  "iat": 1717427688,
+  "exp": 1717463688
+}
+```
+
+### 2. Refresh token
+
+To refresh and obtain a new access token call `/auth/token/refresh/` endpoint with `GET` method.
+
+```bash
+curl -v http://localhost:8000/api/auth/token/refresh \
+  --cookie 'refreshToken=<jwt-refresh-token>'
+```
+
+Response
+
+```
+...
+< Set-Cookie: accessToken=<jwt-access-token>; Path=/; HttpOnly
+< Set-Cookie: refreshToken=<jwt-refresh-token>; Path=/; HttpOnly
+...
+```
+
+> There you get a new token pair
+
+```json
+{
+  "message": "Success",
+  "data": {
+    "userId": 1
+  }
+}
+```
+
+#### Cookies
+
+- `refreshToken` the refresh token that you acquired before
+
+### 3. Change password
+
+To change your account password call `/auth/change-password/` endpoint with `PUT` method.
+
+```bash
+curl --request PUT \
+  --url http://localhost:8000/api/auth/change-password \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "fields": {
+      "currentPassword": "strongpass",
+      "newPassword": "anotherstrongpass"
+    }
+  }' \
+  --cookie 'accessToken=<jwt-access-token>'
+```
+
+Response
+
+```json
+{
+  "message": "Password updated successfully",
+  "data": {
+    "id": 1,
+    "username": "damien"
+  }
+}
+```
+
+#### Body Params
+
+- `fields` containing `currentPassword` and `newPassword` e.g.
+
+```json
+"fields": {
+  "currentPassword": "strongpass",
+  "newPassword": "anotherstrongpass"
+}
+```
+
+#### Cookies
+
+- `accessToken` the access token that you acquired before
+
+### 4. Logout
+
+In order to logout from your account e.g. remove access and refresh cookies and also revoke your refresh token (access token lifetime is very short and doesn't need to be revoked) call `/auth/logout/` endpoint with `GET` method.
+
+```bash
+curl http://localhost:8000/api/auth/change-password \
+  --cookie 'accessToken=<jwt-access-token>' \
+  --cookie 'refreshToken=<jwt-refresh-token>'
+```
+
+Response
+
+```json
+{
+  "message": "Logout successful"
+}
+```
+
+#### Cookies
+
+- `accessToken` the access token that you acquired before
+- `refreshToken` the refresh token that you acquired before