Authentication
Configure login, API keys, rate limiting, and password storage.
Comicarr uses JWT session cookies for the web UI, optional API key access for a limited set of library endpoints, and several security hardening features.
HTTP Authentication
| Setting | Type | Default | Description |
|---|---|---|---|
HTTP_USERNAME | string | — | Login username. |
HTTP_PASSWORD | string | — | Login password. Stored as a bcrypt hash. |
Credentials are created during first-run setup. Do not hand-edit the bcrypt hash in config.ini.
Authentication Mode
| Setting | Type | Default | Description |
|---|---|---|---|
AUTHENTICATION | int | 2 | Historical Mylar-era mode flag. First-run setup sets form-based login (2). The FastAPI UI uses form login + JWT sessions. |
The modern web UI always uses form login with a JWT cookie. Treat basic-auth mode (0) as legacy.
Session Management
| Setting | Type | Default | Description |
|---|---|---|---|
LOGIN_TIMEOUT | int | 43800 | JWT token expiry in minutes. Default is approximately 30 days (43,800 minutes). |
Sessions are JWT-based (HS256). The signing key lives under SECURE_DIR (default <data_dir>/.secure/), separate from the Fernet master key.
The token is set as an HttpOnly, SameSite=Strict cookie named comicarr_session.
CSRF Protection
Comicarr requires a custom header on all state-changing requests:
| Parameter | Value |
|---|---|
| Required header | X-Requested-With: ComicarrFrontend |
| Affected methods | POST, PUT, DELETE, PATCH |
| Exempt paths | /opds, /api/health |
Security Headers
| Header | Value |
|---|---|
X-Content-Type-Options | nosniff |
X-Frame-Options | DENY |
Referrer-Policy | strict-origin-when-cross-origin |
Permissions-Policy | camera=(), microphone=(), geolocation=() |
Cross-Origin-Opener-Policy | same-origin |
X-XSS-Protection | 0 |
Content-Security-Policy | Restricts sources for scripts, styles, images, etc. |
Strict-Transport-Security | Added when ENABLE_HTTPS is true |
Setup Gate
On first run, Comicarr blocks non-setup requests until credentials are configured. Allowed paths include:
/,/index.html,/login/api/auth/setup,/api/auth/check-setup/assets,/favicon.ico/api/health
A setup token is printed to the console / container logs and must be supplied to /api/auth/setup when active.
API Access
| Setting | Type | Default | Description |
|---|---|---|---|
API_KEY | string | auto-generated | Persistent API key for library browse endpoints. |
API_ENABLED | bool | set true when a key is generated | API key auth for supported routes. |
On first startup Comicarr generates a 32-character API key and enables API key support. Regenerate under Settings → API & providers.
Pass the key as the X-Api-Key header on the API key endpoints. Most app routes require a session cookie, not an API key.
Rate Limiting
Login is rate-limited against brute-force attacks:
| Parameter | Value |
|---|---|
| Maximum attempts | 5 per IP |
| Lockout duration | 300 seconds (5 minutes) |
These values are hardcoded.
Password Storage
Comicarr uses bcrypt with 12 salt rounds for password hashing.
| Setting | Type | Default | Description |
|---|---|---|---|
ENCRYPT_PASSWORDS | bool | True | Enable bcrypt hashing for stored passwords. |
SECURE_DIR | string | <data_dir>/.secure | Directory for jwt.key, master.key, and related secrets. |
Legacy Migration
Older installations may have passwords stored as base64-encoded strings. Comicarr detects these and migrates them to bcrypt. No user action is required.
Do not manually edit HTTP_PASSWORD in config.ini. Use first-run setup or the web UI to change your password.