155 lines
4.3 KiB
Markdown
155 lines
4.3 KiB
Markdown
# 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.
|