Search documentation

Search documentation pages and headings.

Skip to content

Getting started · Concept

Setup methods

Compare proxy, OAuth, and auth-subdomain integrations and choose the right boundary for your application.

Install the SDK in consumer applications:

bash
bun add @krak-stack/auth effect

Create a project in Admin > Projects when you need shared branding and enabled sign-in methods. Projects are recommended for a consistent auth experience but are not required by every API payload.

Proxy /api/auth/* from your application to Krakstack Auth. Browser cookies remain first-party to the application origin and the Better Auth client calls a same-origin endpoint. This is the pattern used by Kokobi.

Use this for first-party TanStack Start applications unless you need a standards-only integration.

env
KRAKSTACK_AUTH_URL=https://auth.example.comVITE_KRAKSTACK_AUTH_PROJECT_ID=project_id

KRAKSTACK_AUTH_URL is server-only. The project ID is public and optional. Add KRAKSTACK_AUTH_SERVICE_API_KEY separately only when the application uses trusted service APIs or AuthMiddleware.

Continue with the complete proxy guide.

2. OAuth / OpenID Connect#

Register an OAuth client and use authorization code flow with PKCE. This method works with standard OAuth and OIDC libraries and keeps the consumer independent of Better Auth's browser client.

Current admin-created OAuth clients are confidential Web clients using client_secret_basic and required PKCE. Use this method for separately operated server-backed applications or systems that support this OIDC client model.

Read the service metadata and use its exact issuer and endpoint values. Better Auth's effective issuer can include /api/auth; do not infer it from the bare public origin.

Continue with the OAuth guide.

3. Dedicated auth subdomain#

Register a hostname such as auth.customer.example.com and link it to a project or organization. Users visit a branded auth origin while the application remains at customer.example.com.

Use this when customers require branded authentication domains, several applications share one login surface, or the auth service must be clearly separated from application routes.

Continue with the subdomain guide and domain registration.

Decision checklist#

  • Choose proxy for the shortest, safest first-party setup.
  • Choose OAuth for standards-based portability and delegated authorization.
  • Choose subdomain for a branded central auth hostname and shared parent-domain cookies where supported.
  • Combine OAuth with a custom auth domain when both standard protocol support and branded issuer URLs are required.