Blablador Token Generator

The Token Generator issues the API tokens people use to call Blablador, the LLM service of Helmholtz AI at Forschungszentrum Jülich. People sign in with JSC Login (Unity-IDM, OAuth 2.0), create personal tokens on a dashboard, and the Blablador API gateway checks each presented token with this service.

Documentation: https://helmholtzai-fzj.github.io/blablador-token-generator/

Quick start

uv sync --frozen --all-extras
cp config.yaml.example config.yaml     # then follow the getting-started guide
./start.sh development                 # http://127.0.0.1:8080

Getting started explains the development configuration and how to create the first administrator (python -m app.manage create-local-admin).

Validating a token

curl -X POST https://tokens.example.org/api/v1/auth/validate \
     -H "Authorization: Bearer blablador-…"
# 200 {"valid": true, "user_id": "…", "expires_at": "…+00:00", "error": null}
# 401 for unknown, revoked or expired tokens

See the API reference.

Deployment

Production runs on Kubernetes with the Helm chart in helm/blablador-token-generator: the application, a hardened PostgreSQL and Redis, all over verified TLS, with network policies and optional nightly backups. Docker Compose is supported for single hosts. Start with the production checklist.

Images for the production cluster live in the JSC registry (registry.jsc.fz-juelich.de/kaas/rke2-clusters/blablador/). Tagged releases are built, scanned and published by CI to ghcr.io/helmholtzai-fzj/, and to the JSC registry when its credentials are configured.

Development

uv run pytest                     # tests (SQLite; set TEST_DATABASE_URL for PostgreSQL)
uv run --only-group lint ruff check .  # lint
uv run --only-group docs mkdocs serve

Schema changes are Alembic migrations in app/migrations/; see Development. Changes are recorded in CHANGELOG.md.

Security

Report vulnerabilities privately, as described in SECURITY.md. The October 2026 security audit, with its threat model, control inventory and evidence, is in security_audit/.

License

MIT, see LICENSE.