# Kotauth

> Kotauth is an open-source, self-hosted identity and authentication platform. It provides OAuth 2.0, OpenID Connect, multi-tenant workspaces, magic-link passwordless auth, email OTP passwordless auth, white-label auth screens, transactional email branding, RBAC with client default roles, custom JWT claims with configurable token audience, admin impersonation, tenant backup & restore, Redis distributed sessions, i18n, webhooks, MFA with TOTP replay + lockout protection, refresh-token replay detection, bootstrap API keys, and non-root container hardening — packaged as a single Docker image deployable with one command.

Kotauth is built with Kotlin/Ktor and backed by PostgreSQL. It targets teams who want full control over their auth infrastructure without depending on third-party SaaS. Each workspace is fully isolated with its own RSA key pair, user base, and slug-routed API at `/t/{workspace}/api/v1`.

- License: MIT
- Source: [GitHub](https://github.com/InumanSoul/kotauth)
- Live demo: [demo.kotauth.com](https://demo.kotauth.com)

## Getting Started

- [Introduction](https://docs.kotauth.com/getting-started/introduction/): What Kotauth is and who it's for
- [Quickstart](https://docs.kotauth.com/getting-started/quickstart/): Deploy Kotauth with a single docker compose command
- [Core Concepts](https://docs.kotauth.com/getting-started/core-concepts/): Workspaces, users, roles, groups, applications, and API keys
- [Demo Mode](https://docs.kotauth.com/getting-started/demo/): KAUTH_DEMO_MODE for public showcase deployments

## Authentication

- [Overview](https://docs.kotauth.com/authentication/overview/): Supported authentication methods
- [Email & Password](https://docs.kotauth.com/authentication/email-password/): Password-based auth with bcrypt hashing
- [Magic Links](https://docs.kotauth.com/authentication/magic-links/): Passwordless email login with same-device binding
- [Social Login](https://docs.kotauth.com/authentication/social-login/): Google and GitHub OAuth with automatic account linking
- [Email OTP](https://docs.kotauth.com/authentication/email-otp/): 6-digit code passwordless auth with find-or-create semantics and cross-challenge lockout
- [MFA / TOTP](https://docs.kotauth.com/authentication/mfa/): Multi-factor authentication with recovery codes, TOTP replay protection, and per-enrollment lockout
- [User Invitations](https://docs.kotauth.com/authentication/user-invitations/): Admin-initiated invite emails with 72-hour activation
- [Custom JWT Claims](https://docs.kotauth.com/authentication/custom-claims/): Per-user attributes projected into access and ID tokens
- [Authorization Code + PKCE](https://docs.kotauth.com/authentication/authorization-code/): OAuth 2.0 Authorization Code flow
- [Client Credentials](https://docs.kotauth.com/authentication/client-credentials/): Machine-to-machine auth
- [Token Lifecycle](https://docs.kotauth.com/authentication/token-lifecycle/): Access tokens, refresh tokens, replay detection, family revocation, expiration, and revocation

## OpenID Connect

- [Overview](https://docs.kotauth.com/oidc/overview/): OIDC support and compliance
- [Discovery](https://docs.kotauth.com/oidc/discovery/): .well-known/openid-configuration endpoint
- [Authorization](https://docs.kotauth.com/oidc/authorization/): Authorization endpoint details
- [Token](https://docs.kotauth.com/oidc/token/): Token endpoint and grant types
- [UserInfo](https://docs.kotauth.com/oidc/userinfo/): UserInfo endpoint and claims
- [Introspection & Revocation](https://docs.kotauth.com/oidc/introspection-revocation/): RFC 7662 and RFC 7009 support

## REST API

- [API Overview](https://docs.kotauth.com/api/overview/): Authentication, pagination, error format
- [Users](https://docs.kotauth.com/api/users/): CRUD operations for user management
- [Roles](https://docs.kotauth.com/api/roles/): Role-based access control
- [Groups](https://docs.kotauth.com/api/groups/): Group management and membership
- [Applications](https://docs.kotauth.com/api/applications/): OAuth client/application management, client default roles, and custom token audience
- [Sessions](https://docs.kotauth.com/api/sessions/): Active session management
- [Audit Logs](https://docs.kotauth.com/api/audit-logs/): Audit trail with event filtering
- [User Attributes](https://docs.kotauth.com/api/user-attributes/): Per-user key-value metadata
- [Claim Mappers](https://docs.kotauth.com/api/claim-mappers/): Map user attributes to JWT claims

## AI-Native Management (MCP)

- [Overview](https://docs.kotauth.com/mcp/overview/): Manage Kotauth from Claude, Cursor, or any MCP client
- [Setup](https://docs.kotauth.com/mcp/setup/): Install and configure the MCP server
- [Tool Reference](https://docs.kotauth.com/mcp/tools/): All 33 tools across 8 domains
- [Examples](https://docs.kotauth.com/mcp/examples/): Common workflows and recipes

## Deployment

- [Docker](https://docs.kotauth.com/deployment/docker/): Docker image, compose files, and container config
- [Environment Variables](https://docs.kotauth.com/deployment/environment-variables/): Full configuration reference
- [External Database](https://docs.kotauth.com/deployment/external-database/): Connect to RDS, Supabase, Neon, or any PostgreSQL
- [Production](https://docs.kotauth.com/deployment/production/): Production hardening, non-root container (UID 10001), bootstrap API keys, and best practices
- [Key Rotation](https://docs.kotauth.com/deployment/key-rotation/): RS256 signing key rotation with zero-downtime rollover
- [Backup & Restore](https://docs.kotauth.com/deployment/backup-restore/): Encrypted tenant export and import

## Customization

- [Theming](https://docs.kotauth.com/customization/theming/): Per-tenant CSS variables for white-label auth screens
- [Email Branding](https://docs.kotauth.com/customization/email-branding/): Per-tenant transactional email branding — brand name, color, logo, support email, and from display name
- [Webhooks](https://docs.kotauth.com/customization/webhooks/): HMAC-SHA256 signed event payloads with retry logic

## Security

- [Security Overview](https://docs.kotauth.com/security/overview/): Cryptographic primitives, transport hardening, and secrets storage policy
- [Refresh Token Replay Detection](https://docs.kotauth.com/security/replay-detection/): Automatic family revocation on replay, confidential client auth on refresh grant
- [TOTP Replay + Lockout](https://docs.kotauth.com/security/totp-protection/): Per-enrollment TOTP replay prevention and configurable lockout
- [Container Hardening](https://docs.kotauth.com/security/container-hardening/): Non-root UID 10001, no-new-privileges, cap_drop ALL, read-only filesystem
- [Bootstrap API Keys](https://docs.kotauth.com/security/bootstrap-api-keys/): KAUTH_BOOTSTRAP_API_KEYS env var, idempotent upsert, hash-api-key CLI