Add examples for auth endpoints

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
 

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