Login
Authenticate and receive a JWT token for accessing the API.
Endpoint
POST /login
Headers
| Header | Value |
|---|---|
Content-Type | application/json |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
username | string | ✅ | The username of your account |
password | string | ✅ | The password for your account |
Example Request
curl -X POST -H "Content-Type: application/json" \
-d '{"username": "admin", "password": "password"}' \
http://localhost:9000/login
Response
Success Response (200 OK)
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MjY3NDQ4NDMsInVzZXJuYW1lIjoiYWRtaW4ifQ.eYkCNem24-6rpw8aXo6NIcN6xtU9rqq2_2YYz1nS82Q"
}
Response Fields
| Field | Type | Description |
|---|---|---|
token | string | JWT token for authenticating subsequent API requests |
Error Responses
| Status | Body | When |
|---|---|---|
400 | {"error": "invalid request body"} | The body is not valid JSON |
401 | {"error": "invalid username or password"} | Unknown username or wrong password |
429 | {"error": "too many attempts, try again later"} | Rate limit exceeded, see below |
503 | {"error": "service temporarily unavailable"} | Redis is unavailable, so the rate limit cannot be checked |
Rate Limiting
Login attempts are limited in fixed one-minute windows:
- 10 attempts per minute per client IP
- 5 attempts per minute per username, counted whether or not the username exists. A successful login resets the counter for that username.
When a limit is exceeded, the API responds with 429 Too Many Requests and a Retry-After header holding the number of seconds until the current window ends. The response is the same for both limits and does not reveal whether the username exists.
The client IP is taken from X-Forwarded-For only when the request comes from a proxy listed in TRUSTED_PROXIES.
Notes
- The JWT token should be included in the
Authorizationheader asBearer <token> - Tokens have an expiration time - you may need to re-authenticate periodically
- Store the token securely and do not share it with unauthorized parties
- Use this token for all authenticated API endpoints
- If authentication fails, check your username and password credentials