1 files changed, 69 insertions, 0 deletions
diff --git a/auth/login.md b/auth/login.md
new file mode 100644
index 0000000..ea9ea46
--- /dev/null
+++ b/auth/login.md
@@ -0,0 +1,69 @@
+# POST /auth/login
+
+[back to auth](README.md) /// [home](../README.md)
+
+Authenticate and get a session token. No auth required (obviously).
+
+## Request Body
+
+```json
+{
+  "method": "password",
+  "username": "admin",
+  "password": "secret"
+}
+```
+
+## Fields
+
+| Field          | Type   | Required      | Notes                                         |
+|----------------|--------|---------------|-----------------------------------------------|
+| `method`       | string | yes           | `password`, `pin` or `token`                  |
+| `username`     | string | password, pin | required for password and pin methods         |
+| `password`     | string | password      | only for password method                      |
+| `pin`          | string | pin           | only for pin method                           |
+| `login_string` | string | token         | only for token method (NFC cards, badges etc) |
+
+## Auth Methods
+
+### password
+Standard username + password. No EyePee Restrictions.
+
+### pin
+Short numeric PIN for quick auth (like kiosk scenarios). The clients IP **must** be whitelisted in the servers security config or its a 403. This is a hard requirement, there should never be a bypass for this. ever. seriously. (unless you are dumb enough to set whitelisted IP's to 0.0.0.0/0 for whatever reason but then thats your own fault dumbass)
+
+### token
+Login string based auth for things like NFC card scans or badge readers. Same deal as PIN, clients IP **must** be whitelisted or its 403.
+
+## Success Response
+
+```json
+{
+  "success": true,
+  "token": "your-session-token-here",
+  "user": {
+    "id": 1,
+    "username": "admin",
+    "name": "Full Name",
+    "role": "administrators",
+    "power": 100
+  }
+}
+```
+
+Store the `token` and send it on all future requests as `Authorization: Bearer <token>`.
+
+The `user` object gives you basic info about whos logged in. `power` is the users power level (1 lowest, 100 highest) which determines what jsonderulo lets them do.
+
+## Error Responses
+
+| Code | When                                                                         |
+|------|------------------------------------------------------------------------------|
+| 400  | missing required fields for the chosen method                                |
+| 401  | wrong password, wrong pin, wrong login_string, user not found, user inactive |
+| 403  | IP not whitelisted (pin and token methods only)                              |
+| 500  | database error                                                               |
+
+## Concurrent Sessions
+
+Each user should have a max number of concurrent sessions (configurable per power level + a global default). When a user logs in and is already at the limit the **oldest** session should get automatically evicted from json derulos premises!