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.