1 files changed, 46 insertions, 0 deletions
diff --git a/auth/clear_sessions.md b/auth/clear_sessions.md
new file mode 100644
index 0000000..4c597ee
--- /dev/null
+++ b/auth/clear_sessions.md
@@ -0,0 +1,46 @@
+# POST /auth/clear-sessions
+
+[back to auth](README.md) /// [home](../README.md)
+
+Adminier endpoint to nuke all active sessions for a specific user. Useful when you need to force someone to relogin or if an account might be compromised.
+
+Requires a power level equal to or greater than `min_clear_sessions_power` (configurable).
+
+## Request Body
+
+```json
+{
+  "user_id": 42
+}
+```
+
+| Field     | Type    | Required | Notes                                        |
+|-----------|---------|----------|----------------------------------------------|
+| `user_id` | integer | yes      | the user whose sessions you want to kill duh |
+
+## Success Response (200)
+
+```json
+{
+  "success": true,
+  "sessions_cleared": 3,
+  "user_id": 42
+}
+```
+
+`sessions_cleared` tells you how many sessions were murdered. If the user had no active sessions its 0 and thats still a success.
+
+## Error Responses
+
+| Code | When                        |
+|------|-----------------------------|
+| 401  | no token or invalid session |
+| 403  | your power level is too low |
+
+The 403 error message optionally may tell you what power level is required.
+
+## Notes
+
+- this only affects the targeted users sessions obv. your own stays alive
+- works on any user including yourself if you want to nuke your own other sessions
+- cleared sessions are removed from both the in memory cache and the database (if persistent sessions are on and supported obv.)