Getting started · Concept
Krakstack Auth documentation
Central authentication, organization membership, and identity infrastructure for every application in your stack.
Krakstack Auth is a central identity service built on Better Auth. It owns credentials, sessions, OAuth clients, organizations, API keys, two-factor authentication, and OpenID Connect metadata. Your applications consume identity instead of each implementing a separate authentication system.
Krakstack Auth is currently self-hosted software only.
auth.krakstack.nethosts these docs and the maintainer's own instance; it is not a managed multi-customer auth service. The current published image embeds official-instance build values, so custom operators must review the configuration limitations before deployment.
Start by task
| Goal | Start here |
|---|---|
| Connect a first-party Web application | Application quickstart |
| Choose proxy, OAuth, or a custom hostname | Setup methods |
| Understand identities and trust boundaries | Architecture |
| Configure the SDK and backend | SDK exports and API middleware |
| Manage projects, organizations, clients, and keys | Administration |
| Deploy and operate the service | Self-hosting and configuration |
What it provides
- Email and password, email codes, Google sign-in, and TOTP two-factor authentication
- Shared users and organizations across multiple applications
- OAuth 2.1 authorization code flow and OpenID Connect discovery
- Reusable React forms, account controls, organization switching, and access guards
- Project-specific branding, CSS themes, logos, and enabled sign-in methods
- Custom authentication domains linked to projects or organizations
- Typed Effect HttpApi clients for trusted server-to-server work
Choose an integration
| Method | Best for | Session location | Complexity |
|---|---|---|---|
| Proxy (recommended) | First-party web applications | Your application origin | Low |
| OAuth / OIDC | Independent apps, third parties, and standard identity libraries | Application-defined | Medium |
| Auth subdomain | Branded central sign-in across several apps | Dedicated auth hostname | Medium |
Start with the setup guide. The proxy method gives browsers a same-origin /api/auth/* endpoint while Krakstack Auth remains the source of truth. Choose OAuth when protocol portability matters, or a subdomain when a branded central login hostname is the primary requirement.
Architecture
The browser uses the consumer application's origin. Auth API traffic is either proxied to Krakstack Auth, redirected through OAuth, or sent to a registered authentication hostname. Trusted backend operations use @krak-stack/auth with a service API key.
Never expose KRAKSTACK_AUTH_SERVICE_API_KEY in a VITE_* variable or browser bundle. Browser sessions and service credentials have different trust boundaries.
Next steps
- Confirm that the auth service and administration boundary are configured.
- Create a project when shared branding or sign-in configuration is required.
- Choose one of the three setup methods.
- Add the React provider and CSS source when using packaged components.
- Register production origins, redirect URIs, or domains before launch.
- Review the security and deployment checklists.