Release: v0.1.0-alpha

2026-04-05 16:56:16 +02:00
parent 23ff731579
commit fd13e67aef
89 changed files with 18786 additions and 0 deletions
@@ -0,0 +1,154 @@
+# API Reference
+
+Keywarden is primarily a web application with server-rendered HTML pages. It provides a limited JSON API for health monitoring and internal use.
+
+## Public Endpoints
+
+### Health Check
+
+```
+GET /api/health
+```
+
+Returns the application health status. No authentication required. Used by Docker HEALTHCHECK and external monitoring tools.
+
+**Response (healthy):**
+
+```json
+{
+  "status": "healthy",
+  "uptime": "2d 5h 30m",
+  "uptime_seconds": 194400,
+  "checks": {
+    "database": {
+      "status": "ok"
+    }
+  }
+}
+```
+
+**Response (unhealthy):**
+
+```json
+{
+  "status": "unhealthy",
+  "uptime": "0m",
+  "uptime_seconds": 30,
+  "checks": {
+    "database": {
+      "status": "fail"
+    }
+  }
+}
+```
+
+| Status Code | Meaning |
+|---|---|
+| `200 OK` | Application is healthy |
+| `503 Service Unavailable` | Database unreachable or other critical failure |
+
+## Internal API Endpoints
+
+These endpoints require authentication and are used by the web UI.
+
+### Cron Keys API
+
+```
+GET /api/cron/keys?user_id={id}
+```
+
+Returns SSH keys for a specific user as JSON. Used by the cron job creation form to dynamically load keys when the target user is selected.
+
+**Access**: Admin and Owner only.
+
+**Response:**
+
+```json
+[
+  {
+    "id": 1,
+    "name": "My Ed25519 Key",
+    "key_type": "ed25519",
+    "fingerprint": "SHA256:abc..."
+  }
+]
+```
+
+## HTTP Routes Overview
+
+### Public Routes (No Authentication)
+
+| Method | Path | Description |
+|---|---|---|
+| GET/POST | `/login` | Login page and authentication |
+| POST | `/login/mfa` | MFA code verification |
+| GET | `/logout` | Session termination |
+| GET/POST | `/invite/{token}` | Invitation acceptance |
+
+### Authenticated Routes (All Users)
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/` | Redirect to dashboard |
+| GET | `/dashboard` | Main dashboard |
+| GET/POST | `/password/change` | Forced password change |
+| GET | `/keys` | SSH key list |
+| GET/POST | `/keys/generate` | Generate new SSH key |
+| GET/POST | `/keys/import` | Import existing SSH key |
+| GET/POST | `/keys/{id}/{action}` | Key actions (download, delete) |
+| GET/POST | `/settings` | User account settings |
+| POST | `/settings/theme` | Change theme preference |
+| GET/POST | `/settings/mfa/setup` | Enable MFA |
+| POST | `/settings/mfa/disable` | Disable MFA |
+| POST | `/settings/email/notify` | Toggle email notifications |
+| POST | `/settings/avatar` | Upload profile picture |
+| GET | `/avatar/{id}` | Serve user avatar |
+| GET | `/audit` | Audit log viewer |
+| GET | `/my/access` | View own access assignments |
+| GET/POST | `/mfa/setup` | MFA enforcement setup page |
+
+### Admin Routes (Admin + Owner)
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/servers` | Server list |
+| GET/POST | `/servers/add` | Add server |
+| POST | `/servers/test` | Test server connection |
+| POST | `/servers/test-auth` | Test SSH authentication |
+| GET/POST | `/servers/{id}/{action}` | Edit/delete server |
+| GET | `/groups` | Server group list |
+| GET/POST | `/groups/add` | Add server group |
+| GET/POST | `/groups/{id}/{action}` | Edit/delete group, manage members |
+| GET/POST | `/deploy` | Manual key deployment |
+| POST | `/deploy/group` | Group deployment |
+| GET | `/cron` | Cron job list |
+| GET/POST | `/cron/add` | Add cron job |
+| GET/POST | `/cron/{id}/{action}` | Edit/delete/pause cron job |
+| GET | `/users` | User list |
+| GET/POST | `/users/add` | Add user |
+| GET/POST | `/users/{id}/{action}` | Edit/delete/unlock user |
+| GET | `/assignments` | Access assignment list |
+| GET/POST | `/assignments/add` | Add assignment |
+| GET/POST | `/assignments/{id}/{action}` | Edit/delete/sync assignment |
+| GET | `/system` | System information |
+| GET | `/api/cron/keys` | Get keys by user (JSON) |
+
+### Owner Routes
+
+| Method | Path | Description |
+|---|---|---|
+| GET/POST | `/admin/settings` | Application and security settings |
+| POST | `/admin/settings/email/test` | Send test email |
+| POST | `/admin/masterkey/regenerate` | Regenerate system master key |
+| POST | `/admin/backup/export` | Export encrypted database backup |
+| POST | `/admin/backup/import` | Import encrypted database backup |
+
+## Static Assets
+
+| Path | Description |
+|---|---|
+| `/static/css/` | Tabler CSS framework |
+| `/static/js/` | Tabler JavaScript |
+| `/static/css/fonts/` | Tabler icons font |
+
+Static assets are embedded in the binary and served with long cache headers.