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/domains | bearer | Reserved for future use |
| GET | /api/accounts | bearer | Reserved for future use |
| GET | /api/aliases | bearer | Reserved for future use |
All API endpoints (except /, /health, and /readyz) require an Authorization: Bearer <token> header. Tokens are 64-character hex strings. Generate one with mailacc -g 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.