FeaturesAuthentication

Integration

Step-by-step auth integration for an existing web app.

What It Does

Defines the minimum integration contract for using @kit/auth in an app that did not come from CLI generation.

When To Use

Retrofitting auth into an existing app.

Prerequisites

App has Supabase client/server setup.
Route constants available through @kit/shared/config/routes.

Important

This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs.

How To Use

Create config.

Add config/auth.config.ts using parseAuthConfig.

Add proxy enforcement.

proxy.ts

import { authProxy } from '@kit/auth/www/proxy/auth';
import { NextResponse, type NextRequest } from 'next/server';
import { authConfig } from './config/auth.config';
 
export async function proxy(request: NextRequest): Promise<NextResponse> {
  const response = NextResponse.next();
  const maybeAuthResponse = await authProxy(authConfig)(request, response);
  return maybeAuthResponse ?? response;
}

Wrap app with `AuthProvider`.

import { AuthProvider } from '@kit/auth/www/ui/auth-provider';
import { authConfig } from '~/config/auth.config';
 
<AuthProvider authConfig={authConfig}>{children}</AuthProvider>

Add auth route pages.

Use AuthPages in app/auth/[path]/page.tsx.
Add callback route in app/auth/callback/route.ts.

Filter API

Auth integration relies on filters for redirect customization and package translation registration.

Filter	Parameters	Return	Registered By (package file)	Initialized In (app entrypoint)	Environment
`auth_on_sign_in_redirect_url`	`{}`	`string`	`kit/organization/src/www/filters/use-filters/use-auth-filters.tsx`	`apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`)	`client`
`auth_on_sign_up_redirect_url`	`{}`	`string`	`kit/organization/src/www/filters/use-filters/use-auth-filters.tsx`	`apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`)	`client`
`cross_env_get_translations`	`{ language: string; namespace: string }`	`Record<string, string> \| null`	`kit/auth/src/www/filters/cross-env-filters.ts`	`apps/dashboard/lib/init-cross-env-filters.ts`	`cross-env`
`cross_env_get_namespaces`	`{}`	`string[]`	`kit/auth/src/www/filters/cross-env-filters.ts`	`apps/dashboard/lib/init-cross-env-filters.ts`	`cross-env`

Init Checklist

Keep useOrgFilters({ orgConfig }) in apps/dashboard/hooks/use-filters.ts.
Keep initAuthFilters() in apps/dashboard/lib/init-cross-env-filters.ts.

MCP Context


capability: auth_web_integration
entrypoints:
  - proxy.ts
  - app/auth/[path]/page.tsx
  - app/auth/callback/route.ts
  - app/layout.tsx
  - kit/organization/src/www/filters/use-filters/use-auth-filters.tsx
  - kit/auth/src/www/filters/cross-env-filters.ts
  - apps/dashboard/hooks/use-filters.ts
  - apps/dashboard/lib/init-cross-env-filters.ts
inputs:
  - auth_config
outputs:
  - authenticated_route_guarding
constraints:
  - proxy matcher must include protected pages
side_effects:
  - redirects unauthenticated users to auth pages

Agent Recipe

Add auth.config.ts.
Add proxy integration.
Add provider in app tree and auth routes.

Troubleshooting

If protected routes are open, verify proxy matcher covers those paths.
If everything redirects to sign-in, verify session cookies and callback route.

Authentication

Authentication

Web authentication architecture using Supabase and @kit/auth.

Retrieve User

Access authenticated user data on server and client.

How is this guide?

Last updated on 3/27/2026