AgentFlow Enterprise Docs

Authentication & Session Model

Supabase Auth establishes user sessions. Server routes resolve the user and organization before tenant data, billing, and AI operations run.

Supabase Auth Role

AgentFlow uses Supabase Auth for email/password and OAuth-backed user identity. Server-side clients are created with @supabase/ssr; browser clients use the anon key and are constrained by RLS.

Role	Meaning
`anon`	Unauthenticated browser role. Public reads such as plan metadata can be allowed, but tenant data is not.
`authenticated`	Signed-in user role. Access is tenant-scoped by active organization membership and grants.
`service_role`	Server-only administrative role used by trusted backend routes and webhooks. It bypasses RLS and must never be exposed.

Login and Session Flow

Public /login and /signup routes collect auth intent and redirect through Supabase.
/api/auth/callback exchanges auth callback data with the Supabase server client.
proxy.ts checks the session for /dashboard/:path*, /login, and /signup.
Unauthenticated dashboard requests redirect to /login.
Signed-in users visiting /login or /signup are redirected to a safe return path or /dashboard.

Organization Membership Checks

Server routes use getCurrentUser, getUserOrganization, and getOrCreateDefaultOrganizationForUser to resolve the authenticated user and default organization. AI and billing routes run organization-scoped queries with the Supabase service role after this resolution.

RLS policies still protect browser-originated Supabase calls. Server-only operations must validate the user, organization, and intended action before using the service-role client.

Safe Debugging Checklist

Symptom	Check
Expired session	Refresh login, inspect Supabase session cookie behavior, and verify `/api/auth/callback`.
Missing membership	Confirm `organization_members` contains an active row for the user and organization.
RLS denial	Use a non-production tenant isolation test; confirm row `organization_id` matches active membership.
Service role missing	Confirm `SUPABASE_SERVICE_ROLE_KEY` exists in the deployment environment; never paste the value into logs.
Redirect loop	Check `proxy.ts` matcher, `returnUrl`, Supabase URL/anon key, and callback URLs.

These docs describe implementation readiness and configuration. They are not a SOC 2, ISO 27001, penetration test, or contractual SLA claim.