Core Concepts

Authentication

How Minerva authenticates users and services — Keycloak JWT sessions and API key Bearer tokens.

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

Method	Best for
Session Token (Keycloak JWT)	Interactive use, browser-based apps, user-facing workflows
API Key (mzk_ prefix)	Automated workflows, CI/CD, SDKs, server-side applications

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 }

bash

# 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:

json

{
  "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.

http

Authorization: Bearer mzk_a7f3c2e9d1b84f6a2e0c5d8b3f7a1e4c9d2b5f8a3e6c1d4b7f0a3e6c9d2b5

Note: API keys are prefixed with mzk_ for easy identification in configs and secret scanning rules.

Protected Routes

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

Route	Auth Required
/dashboard	Yes
/proofs	Yes
/circuits	Yes
/chat	Yes
/docs	Yes
/sdk	Yes
/templates	No
/guides	No
/pricing	No
/verify	No

Logout

bash

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.

← Back to Documentation

Documentation

Core Concepts

Authentication

How Minerva authenticates users and services — Keycloak JWT sessions and API key Bearer tokens.

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

Method	Best for
Session Token (Keycloak JWT)	Interactive use, browser-based apps, user-facing workflows
API Key (mzk_ prefix)	Automated workflows, CI/CD, SDKs, server-side applications

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 }

bash

# 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:

json

{
  "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.

http

Authorization: Bearer mzk_a7f3c2e9d1b84f6a2e0c5d8b3f7a1e4c9d2b5f8a3e6c1d4b7f0a3e6c9d2b5

Note: API keys are prefixed with mzk_ for easy identification in configs and secret scanning rules.

Protected Routes

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

Route	Auth Required
/dashboard	Yes
/proofs	Yes
/circuits	Yes
/chat	Yes
/docs	Yes
/sdk	Yes
/templates	No
/guides	No
/pricing	No
/verify	No

Logout

bash

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.

← Back to Documentation

Documentation

Core Concepts

Authentication

How Minerva authenticates users and services — Keycloak JWT sessions and API key Bearer tokens.

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

Method	Best for
Session Token (Keycloak JWT)	Interactive use, browser-based apps, user-facing workflows
API Key (mzk_ prefix)	Automated workflows, CI/CD, SDKs, server-side applications

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 }

bash

# 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:

json

{
  "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.

http

Authorization: Bearer mzk_a7f3c2e9d1b84f6a2e0c5d8b3f7a1e4c9d2b5f8a3e6c1d4b7f0a3e6c9d2b5

Note: API keys are prefixed with mzk_ for easy identification in configs and secret scanning rules.

Protected Routes

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

Route	Auth Required
/dashboard	Yes
/proofs	Yes
/circuits	Yes
/chat	Yes
/docs	Yes
/sdk	Yes
/templates	No
/guides	No
/pricing	No
/verify	No

Logout

bash

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.

← Back to Documentation

Documentation

Core Concepts

Authentication

How Minerva authenticates users and services — Keycloak JWT sessions and API key Bearer tokens.

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

Method	Best for
Session Token (Keycloak JWT)	Interactive use, browser-based apps, user-facing workflows
API Key (mzk_ prefix)	Automated workflows, CI/CD, SDKs, server-side applications

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 }

bash

# 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:

json

{
  "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.

http

Authorization: Bearer mzk_a7f3c2e9d1b84f6a2e0c5d8b3f7a1e4c9d2b5f8a3e6c1d4b7f0a3e6c9d2b5

Note: API keys are prefixed with mzk_ for easy identification in configs and secret scanning rules.

Protected Routes

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

Route	Auth Required
/dashboard	Yes
/proofs	Yes
/circuits	Yes
/chat	Yes
/docs	Yes
/sdk	Yes
/templates	No
/guides	No
/pricing	No
/verify	No

Logout

bash

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.

← Back to Documentation