Authentication

Current state (dev): Most endpoints are open for ease of testing. Auth (JWT/API key) is planned; headers below may be optional in your environment.

Planned Flows

JWT Bearer

• Login: POST /auth/login

{
  "username": "user@example.com",
  "password": "securepassword123"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Use token

GET /api/v1/users/me
Authorization: Bearer <token>

API Key

• Header: X-API-Key: <your_api_key>
• Query (alt): ?api_key=<your_api_key>
• Example (citizen reports list):

curl -H "X-API-Key: your_api_key" \
  "http://localhost:8000/api/v1/citizen-reports?limit=20"

API key creation (when enabled): POST /users/api-keys with name, description (requires auth).

Roles (intended)

Security Notes

• JWT expiry (planned): 30–60 minutes; refresh not yet exposed.
• Passwords stored hashed (e.g., bcrypt) when registration is enabled.
• CORS allowlist configurable via .env (ALLOWED_ORIGINS).
• Use HTTPS in production; keep tokens/API keys in headers, not query when possible.

For full endpoint coverage, see docs/API_REFERENCE.md. In dev, if you hit 401/403, ensure your environment has auth enabled or remove the auth header when testing open endpoints.