Minerva supports two authentication methods: interactive browser sessions backed by Keycloak JWTs, and long-lived API keys for programmatic access.

Session-Based Auth (Keycloak)

When you sign in through the Minerva web interface, you authenticate against a Keycloak identity provider. On success, the server sets an httpOnly session cookie containing a signed JWT.

• •Cookie name: minerva.session
• •Algorithm: HS256 (symmetric, server-side secret)
• •Expiry: 7 days (sliding)
• •Flags: httpOnly, secure, SameSite=lax
• •Payload: { sub, email, name, username, iat, exp }

# Login and capture session cookie
curl -s -c cookies.txt -X POST https://zkesg.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

# Use the cookie on subsequent requests
curl -s -b cookies.txt https://zkesg.com/api/auth/session

The /api/auth/session endpoint returns the current authenticated user:

{
  "authenticated": true,
  "user": {
    "sub": "d8f531d6-...",
    "email": "you@example.com",
    "name": "Your Name",
    "username": "your_username"
  }
}

API Key Auth

API keys provide long-lived access without browser interaction. Pass your key as a Bearer token in the Authorization header on every request.

Authorization: Bearer mzk_a7f3c2e9d1b84f6a2e0c5d8b3f7a1e4c9d2b5f8a3e6c1d4b7f0a3e6c9d2b5

Protected Routes

Middleware enforces authentication on all protected routes. Unauthenticated requests to protected routes receive a 307 redirect to /login.

Logout

curl -s -b cookies.txt -X POST https://zkesg.com/api/auth/logout

This clears the session cookie. The Keycloak session is also invalidated, preventing SSO re-login without credentials.