Password management API for Dovecot mail accounts
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | / | none | API reference (this page) |
| GET | /health | none | Liveness probe. Returns {"status":"ok"} |
| GET | /readyz | none | Readiness probe. Returns {"status":"ok"} or 503 if DB is unreachable |
| GET | /api/user?username=<email> | bearer | Get user details. Returns {"status":"ok","user":{...}} |
| PUT | /api/user/name | bearer | Set first/last name. Body: {"username","first","last"} |
| PUT | /api/user/password | bearer | Set or generate password. Body: {"username","password"}. Empty password generates a random one. |
| POST | /api/user/auth | bearer | Verify password. Returns {"valid":bool} |
| PUT | /api/user/status | bearer | Lock or unlock account. Body: {"username","locked":bool} |
| PUT | /api/user/email | bearer | Set backup email. Body: {"username","email"} |
| GET | /api/user/data?username=<email> | bearer | Get user data JSON. Returns {"status":"ok","data":{...}} |
| PUT | /api/user/data | bearer | Set user data JSON. Body: {"username","data":{...}} |
| GET | /api/accounts?filter=<str> | bearer | List accounts. Optional filter for partial username match. Returns {"status":"ok","accounts":[...]} |
| GET | /api/domains | bearer | List mail domains from the sites table. Returns {"status":"ok","domains":[...]} |
| GET | /api/aliases?target=<email> | bearer | List aliases. Optional target filter. Returns {"status":"ok","aliases":[...]} |
| POST | /api/aliases | bearer | Add one or more aliases. Body: {"aliases":[],"target"}. Returns {"status":"ok","count":N} |
| DEL | /api/aliases | bearer | Remove an alias. Body: {"alias"} |
All API endpoints (except /, /health, and /readyz) require an Authorization: Bearer <token> header. Tokens are 64-character hex strings. Generate one with musr gen-key admin@example.com. Each token corresponds to a .key file in the config directory. Deleting the file immediately revokes the token — no restart needed.
30 requests per 60-second sliding window per IP. Respects X-Forwarded-For. Returns 429 with {"error":"too many requests"} when exceeded.