HVT is an open-source authentication platform built with Django and Django REST Framework. It provides a control plane for organizations, projects, API keys, invites, webhooks, and audit logs, plus a runtime auth plane for customer-facing applications.
- email and password authentication
- JWT access and refresh tokens
- registration, email verification, and password reset
- Google and GitHub social login
- organizations, projects, and API keys
- project-scoped runtime auth with shared identity across projects
- invitations, project roles, permissions, and audit logs
- webhook delivery for organization events
HVT separates two concerns:
- control plane: the dashboard and admin-facing APIs used to manage organizations, projects, API keys, social providers, invites, and webhooks
- runtime plane: project-scoped auth flows that your application uses for sign-up, sign-in, social login, verify-email, and password reset
User accounts are shared at the organization level, while runtime access is enforced per project through direct membership or assigned project roles.
hvt/: Django project and application codedocs/: setup, deployment, webhook, and frontend handoff guidessdk/: pointers to standalone SDK repositoriesscripts/: maintenance and build scripts.github/: CI and contribution templates
git clone https://github.com/markodera/hvt.git
cd hvt
cp .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserverThe API will be available at http://localhost:8000.
cp .env.example .env
docker-compose up --buildThe compose stack starts PostgreSQL, Redis, and the Django API.
Start from .env.example. The checked-in defaults are intentionally local-development oriented. For hosted or production deployment, override the security and domain settings documented in docs/RAILWAY_DEPLOYMENT.md.
If you use runtime auth in a customer-facing app, set each project's frontend_url so email verification and password reset links land on the correct frontend.
- Main app: hvts.app
- Direct API base URL: api.hvts.app
- Documentation: docs.hvts.app
Runtime requests are authenticated with X-API-Key and require the auth:runtime scope.
Key runtime endpoints:
POST /api/v1/auth/runtime/register/
POST /api/v1/auth/runtime/login/
GET /api/v1/auth/runtime/social/providers/
POST /api/v1/auth/runtime/social/google/
POST /api/v1/auth/runtime/social/github/
POST /api/v1/auth/runtime/register/resend-email/
POST /api/v1/auth/runtime/register/verify-email/
POST /api/v1/auth/runtime/password/reset/
POST /api/v1/auth/runtime/password/reset/validate/
POST /api/v1/auth/runtime/password/reset/confirm/<uidb64>/<token>/
- Developer quickstart
- Browser authentication guide
- Webhook guide
- Railway deployment
- Runtime/frontend handoff
- SDK repo split guide
- Open-source release checklist
When running locally, OpenAPI docs are available at /api/docs/ and /api/redoc/ if EXPOSE_API_DOCS=1.
Run checks and tests before opening a pull request:
python manage.py check
python manage.py testContribution, conduct, and security reporting live here:
The TypeScript SDK now lives in its own repository so SDK contributors do not need the backend codebase.
- SDK repo: markodera/hvt-sdk
- NPM package:
@hvt/sdk - Direct API users can integrate against api.hvts.app without using an SDK
HVT is released under the GNU Affero General Public License v3.0 only.