From 78970bf292df1a760fc120e10ddfaaee235db818 Mon Sep 17 00:00:00 2001
From: Radical <radical@radical.fun>
Date: Fri, 2 May 2025 11:55:25 +0200
Subject: [PATCH] docs: add refresh/revoke endpoints for token handling

---
 API/client-server/v1/auth/refresh.md | 60 +++++++++++++++++++++++++++
 API/client-server/v1/auth/revoke.md  | 62 ++++++++++++++++++++++++++++
 2 files changed, 122 insertions(+)
 create mode 100644 API/client-server/v1/auth/refresh.md
 create mode 100644 API/client-server/v1/auth/revoke.md

diff --git a/API/client-server/v1/auth/refresh.md b/API/client-server/v1/auth/refresh.md
new file mode 100644
index 0000000..7e8d8bb
--- /dev/null
+++ b/API/client-server/v1/auth/refresh.md
@@ -0,0 +1,60 @@
+POST /v1/auth/refresh
+
+---
+
+Reauthenticates the user using the refresh token, and issues an access token for future requests.
+
+---
+
+## Request
+
+| Name          | Type   | Description           |
+| ------------- | ------ | --------------------- |
+| refresh_token | string | User's refresh token. |
+
+```json
+{
+  "refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749",
+}
+```
+
+---
+
+## Responses
+
+| Status | Description                                     |
+|--------|-------------------------------------------------|
+| 200    | Authentication successful.                      |
+| 400    | The post request included poorly formated data. |
+| 403    | Part of the cridentials are invalid.            |
+| 500    | An unhandled error occured.                     |
+
+---
+
+### 200
+
+| Name          | Type   | Description                                                                                                                                                                                                                                |
+| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| access_token  | string | **Required**: The access token that will be used for further authentication.                                                                                                                                                               |
+| refresh_token | string | The refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. NOTE: This endpoint returns the same refresh_token if it was generated less than 23 days ago. |
+
+```json
+{
+  "access_token": "85b2afece430e0e924f2d4277324c868",
+  "refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749"
+}
+```
+
+---
+
+### 500
+
+| Name  | Type   | Description                      |
+| ----- | ------ | -------------------------------- |
+| error | string | The error the server encountered |
+
+```json
+{
+  "error": "Something went wrong!",
+}
+```
diff --git a/API/client-server/v1/auth/revoke.md b/API/client-server/v1/auth/revoke.md
new file mode 100644
index 0000000..85c24c4
--- /dev/null
+++ b/API/client-server/v1/auth/revoke.md
@@ -0,0 +1,62 @@
+POST /v1/auth/revoke
+
+---
+
+Revokes authenticated refresh/access tokens owned by the user.
+
+---
+
+## Request
+
+| Name         | Type   | Description                                                                                                 |
+| ------------ | ------ | ----------------------------------------------------------------------------------------------------------- |
+| access_token | string | User's access token to validate the session.                                                                |
+| password     | string | SHA3-384 of user password to ensure its the user trying to do this and not someone who has the access token |
+| device_name  | string | device_name that should be removed from the list of logins (NOTE: Removes all devices with the same name)   |
+
+```json
+{
+  "access_token": "85b2afece430e0e924f2d4277324c868",
+  "password": "f324cbd421326a2abaedf6f395d1a51e189d4a71c755f531289e519f079b224664961e385afcc37da348bd859f34fd1c",
+  "device_name": "Laptop"
+}
+```
+
+---
+
+## Responses
+
+| Status | Description                                     |
+|--------|-------------------------------------------------|
+| 200    | Deletion successful.                            |
+| 400    | The post request included poorly formated data. |
+| 403    | Part of the cridentials are invalid.            |
+| 500    | An unhandled error occured.                     |
+
+---
+
+### 200
+
+| Name    | Type | Description                                                           |
+| ------- | ---- | --------------------------------------------------------------------- |
+| deleted | bool | Returns true if the refresh/access token(s) were successfully deleted |
+
+```json
+{
+  "deleted": true
+}
+```
+
+---
+
+### 500
+
+| Name  | Type   | Description                      |
+| ----- | ------ | -------------------------------- |
+| error | string | The error the server encountered |
+
+```json
+{
+  "error": "Something went wrong!",
+}
+```