📚 For complete documentation, visit authhero.net
AuthHero is a multi-tenant authentication system that provides identity and access management services. This is the main monorepo containing all packages and applications.
- authhero - The main package for AuthHero that handles authentication and API requests
- create-authhero - A CLI for creating new AuthHero projects
- proxy - Multi-tenant reverse proxy for fronting customer custom domains with path-based routing
- Adapters:
adapter-interfaces- Interfaces for creating adapters for AuthHerokysely- ORM adapter for SQL databasesdrizzle- ORM adapter for SQL databases (experimental)cloudflare- Custom domains supportsaml- SAML authentication support
- admin - Admin interface (shadcn/ui + ra-core) for managing tenants, users, applications, and more
- demo - Demo authentication server using the kysely adapter and SQLite
- proxy-dev - Cloudflare Worker harness for developing/deploying
@authhero/proxy - docs - Documentation site powered by VitePress, deployed to Cloudflare Pages at docs.authhero.net — see apps/docs/DEPLOYMENT.md
The fastest way to get started is using the create-authhero CLI:
npm create authhero my-auth-project
cd my-auth-project
pnpm install
pnpm devThis creates a new project with:
- SQLite database for local development
- Pre-configured authentication endpoints
- Example templates you can customize
To manage your authentication system, use the hosted admin interface:
- Go to manage.authhero.net
- Create a tenant or connect to your local instance
- Configure your applications, users, and authentication settings
Clone and set up the monorepo for development:
git clone https://github.com/authhero/authhero.git
cd authhero
pnpm installStart the demo authentication server:
pnpm demo devThis starts a local auth server at http://localhost:8787 with SQLite storage.
Start all apps in development mode:
pnpm devThis starts:
- Demo auth server
- Admin interface
- Documentation site
- All other apps in parallel
Use these shortcuts to work with individual apps:
pnpm demo # Work with demo app
pnpm admin # Work with admin interface
pnpm authhero # Work with main package
pnpm vitepress # Work with docsAuthHero is tested against the OpenID Foundation conformance suite via apps/conformance-runner, a Playwright-driven runner that boots the suite, seeds a local auth-server, and runs the oidcc-basic-certification-test-plan.
One-time setup:
- Clone the conformance suite into
~/conformance-suite(the scripts expect this path). - Add the suite's hostname to
/etc/hosts:127.0.0.1 localhost.emobix.co.uk - Install Playwright's Chromium browser:
pnpm --filter @authhero/conformance-runner exec playwright install chromium
Run the suite from the repo root:
pnpm conformance:start # bring up the suite via Docker
pnpm conformance:run # run the full plan
pnpm conformance:run -- --grep "discovery" # run a single module
pnpm conformance:report # open the last HTML report
pnpm conformance:stop # tear down the suiteSee apps/conformance-runner/README.md for environment variables and advanced options.
We welcome contributions! Here's how to get started:
-
Create a new branch for your changes:
git checkout -b feature/my-feature
-
Make your changes and ensure tests pass:
pnpm test -
Format your code:
pnpm format
AuthHero uses Changesets for version management. When you make changes that should be included in the changelog, create a changeset:
pnpm changesetThis will prompt you to:
- Select packages - Choose which packages are affected by your changes
- Select version bump type:
- Patch (0.0.x) - Bug fixes, documentation updates, non-breaking changes
- Minor (0.x.0) - New features, non-breaking additions
- Major (x.0.0) - Breaking changes that require users to modify their code
- Describe your changes - Write a summary that will appear in the changelog
The changeset will be saved as a markdown file in .changeset/ and should be committed with your changes.
Example:
$ pnpm changeset
🦋 Which packages would you like to include? › authhero
🦋 What kind of change is this for authhero? › minor
🦋 Please enter a summary for this change:
Added support for custom email templates- Push your branch to GitHub
- Open a pull request with:
- Clear description of changes
- Any relevant issue numbers
- Your changeset(s) included
- Wait for review and CI checks to pass
Releases are automated via GitHub Actions when changesets are merged to the main branch. The process:
- Changesets are collected on each PR
- After merge, a "Version Packages" PR is automatically created
- When the Version Packages PR is merged, packages are published to npm
authhero/
├── apps/
│ ├── admin/ # Admin interface (shadcn/ui + ra-core)
│ ├── demo/ # Demo auth server
│ ├── proxy-dev/ # Worker harness for @authhero/proxy
│ └── docs/ # Documentation site
├── packages/
│ ├── adapter-interfaces/
│ ├── authhero/ # Main package
│ ├── cloudflare/
│ ├── create-authhero/ # Project generator CLI
│ ├── drizzle/
│ ├── kysely/
│ ├── proxy/ # Multi-tenant reverse proxy library
│ └── saml/
└── test/ # Integration tests
AuthHero is dual-licensed under AGPL-3.0-only or a commercial license —
see LICENSING.md for the full model and the per-package table. The
integration surfaces stay permissive on purpose: @authhero/adapter-interfaces,
create-authhero (and the apps it scaffolds), and @authhero/widget are MIT, so
using those packages on their own imposes no AGPL obligations on your code. The
AGPL-licensed packages remain subject to AGPL-3.0-only or a commercial license.
Versions published before this change remain MIT. Contributions are accepted under the CLA — see CONTRIBUTING.md.