Authentication (Clerk)

VibeReady uses Clerk for authentication and multi-tenancy. This guide covers the required configuration steps to enable Organizations, session tokens, super admin access, and optional OAuth providers.

---

Enable Organizations (Required)

Multi-tenancy in VibeReady is built on Clerk Organizations. Each organization represents a tenant with its own data, billing, and member management.

To enable Organizations:

1. Go to the Clerk Dashboard.
2. Select your application.
3. Navigate to Configure then Organizations.
4. Click Enable Organizations.

Without this step, users will not be able to create or join organizations and the onboarding flow will not function correctly.

---

Session Token Configuration (Required)

The onboarding flow relies on user metadata embedded in session tokens. This allows the middleware to check onboarding completion status on a per-organization basis.

1. Go to Clerk Dashboard, then Configure then Sessions.
2. Click Edit next to “Customize session token”.
3. Add the following to the Claims field:

{ "metadata": "{{user.public_metadata}}" }

4. Click Save.

If this step is skipped, users may encounter redirect loops during the onboarding flow.

---

Super Admin Setup

Super admins have platform-wide access to the /admin dashboard, which includes user management, organization oversight, and system-level controls.

First Super Admin

After signing up and completing the onboarding flow, you need to grant super admin privileges to your initial user. This is done by setting the isSuperAdmin flag on the user record in the database.

You can do this directly in the database or through Prisma Studio:

make db-studio

This opens a visual database editor at http://localhost:5555. Navigate to the Users table, find your user record, and set isSuperAdmin to true.

Subsequent Super Admins

Once you have super admin access, you can promote other users through the admin UI:

1. Go to /admin/users.
2. Find the user you want to promote.
3. Toggle their super admin status.

All super admin changes are logged in the audit trail for accountability.

---

OAuth Providers (Optional)

You can configure social login providers to offer users a faster sign-up experience.

1. Go to Configure then SSO Connections in the Clerk Dashboard.
2. Enable the providers you want (Google, GitHub, etc.).
3. Add OAuth credentials from each provider’s developer console.

VibeReady works with any OAuth provider supported by Clerk. No application code changes are needed.

---

Troubleshooting

Issue	Solution
”Organization not found”	Enable Organizations in the Clerk Dashboard (see above).
Onboarding redirect loop	Configure the session token with the metadata claim.
Cannot access /admin	Set isSuperAdmin to true on your user record in the database.
OAuth login fails	Verify provider credentials in the Clerk Dashboard.

---

Environment Variables

The following variables are required in your .env.local file and are configured during the initial make setup process:

Variable	Required	Description
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Yes	Publishable key from Clerk Dashboard
CLERK_SECRET_KEY	Yes	Secret key from Clerk Dashboard

---

Related Docs

• Billing (Stripe) — subscription billing tied to organizations
• Background Jobs (Inngest) — event processing for user lifecycle events