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.

---

MCP Server (Optional)

The MCP server (/api/mcp, see MCP Server) authenticates with Clerk machine tokens. Enable these in the Clerk Dashboard:

1. API keys at dashboard.clerk.com/~/platform/api-keys: select Enable API keys and, in the dialog, leave both switches off (Enable User API keys and Enable Organization API keys), then press Enable. The app creates and verifies keys through Clerk’s Backend API (each key is minted for a member on /dashboard/integrations with the organization pinned in its claims), so the self-serve switches are not needed. Leave the user switch off on purpose: it would add an API Keys tab to Clerk’s account modal, and keys minted there carry no organization claim, so the MCP server refuses them. Clerk meters key creation and verification after a free tier; see Clerk’s pricing page.
2. OAuth applications at dashboard.clerk.com/~/oauth-applications:
   • enable the user:org:read scope (it shows an organization picker on the consent screen and stamps org_id on the access token; that is how Claude names its organization);
   • on the Scopes tab, add the custom scopes mcp:read and mcp:write;
   • enable CIMD (preferred) or Dynamic Client Registration so MCP clients such as Claude Desktop can register themselves, and set the default scopes for dynamically registered clients to openid profile email user:org:read mcp:read mcp:write.

No new environment variables: the server derives Clerk’s issuer from NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.

---

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
• MCP Server — expose the assistant’s tools to Claude, Cursor, and scripts