1 files changed, 61 insertions, 0 deletions
diff --git a/auth/status.md b/auth/status.md
new file mode 100644
index 0000000..354ea9b
--- /dev/null
+++ b/auth/status.md
@@ -0,0 +1,61 @@
+# GET /auth/status
+
+[back to auth](README.md) /// [home](../README.md)
+
+Check if your session is still alive and get details about it.
+
+## Request
+
+No body. Token in header:
+```
+Authorization: Bearer <token>
+```
+
+## Valid Session Response (200)
+
+```json
+{
+  "success": true,
+  "valid": true,
+  "user": {
+    "id": 1,
+    "username": "admin",
+    "name": "Full Name",
+    "role": "administrators",
+    "power": 100
+  },
+  "session": {
+    "created_at": "2026-02-14T10:30:00Z",
+    "last_accessed": "2026-02-14T11:45:00Z",
+    "timeout_minutes": 120,
+    "remaining_seconds": 5400,
+    "expires_at": "2026-02-14T13:45:00Z"
+  }
+}
+```
+
+The `session` object tells you when the session was created, when it was last used, how long the timeout is, how many seconds are left and when itll expire if nothing happens.
+
+If session refresh on activity is enabled (which it should be by default) then `last_accessed` gets updated on every request so the session keeps extending as long as youre actively bothering jsonderulo.
+
+## Invalid/Expired Session Response (401)
+
+```json
+{
+  "success": true,
+  "valid": false,
+  "message": "Session expired or invalid [request_id: 12345678]"
+}
+```
+
+Note that `success` is still true here because the status check itself worked fine, the session is just dead lol. Check the `valid` field to know if the session is actually alive.
+
+## No Token Response (401)
+
+```json
+{
+  "success": false,
+  "valid": false,
+  "error": "No authorization token provided [request_id: 12345678]"
+}
+```