Authentication
Session cookies, API keys, CSRF, and rate limiting for the Comicarr API.
Comicarr supports session-based authentication for the full API and a persistent API key for a limited set of library browse endpoints.
Session auth (primary)
Authenticate via the login endpoint to receive an HttpOnly JWT cookie named comicarr_session.
curl -c cookies.txt -X POST http://localhost:8090/api/auth/login \
-H "Content-Type: application/json" \
-H "X-Requested-With: ComicarrFrontend" \
-d '{"username": "admin", "password": "your_password"}'
curl -b cookies.txt http://localhost:8090/api/series| Endpoint | Method | Description |
|---|---|---|
/api/auth/login | POST | JSON login (sets JWT session cookie) |
/api/auth/logout | POST | Invalidate current session |
/api/auth/check-session | GET | Verify if current session is valid |
/api/auth/check-setup | GET | Whether first-run setup is required |
/api/auth/setup | POST | First-run credential setup (requires setup token when active) |
Tokens are signed with HS256 using a key under <data_dir>/.secure/. Expiry is controlled by LOGIN_TIMEOUT (minutes; default 43800 ≈ 30 days).
API key (library browse)
An API key is auto-generated on first startup and stored in config.ini. Regenerate it in Settings → API & providers.
Pass it as the X-Api-Key header:
curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:8090/api/watchlistEndpoints that accept the API key today:
| Method | Path |
|---|---|
| GET | /api/watchlist |
| GET | /api/comics |
| GET | /api/comic/{comic_id} |
| GET | /api/comic/{comic_id}/issues |
| GET | /api/comic/{comic_id}/issue/{issue_id} |
Most other routes require a session cookie, not an API key.
CSRF protection
State-changing methods (POST, PUT, DELETE, PATCH) must include:
X-Requested-With: ComicarrFrontendExempt paths: /opds, /api/health. Combined with SameSite=Strict cookies, this blocks cross-site form posts.
Rate limiting
Failed login attempts are rate-limited per IP:
| Parameter | Value |
|---|---|
| Max attempts | 5 |
| Lockout duration | 300 seconds |
This applies to the login endpoint, not every API call.
First-run setup
When credentials are not configured, Comicarr prints a setup token to the console/logs and blocks non-setup routes until setup completes. Allowed paths include /, /login, /api/auth/setup, /api/auth/check-setup, /api/health, and static assets.