Clerk Setup

Overview

OpenInvoice uses Clerk for authentication, user management, and multi-tenant organizations. This guide covers complete Clerk setup.

Prerequisites

• Clerk account (sign up here)
• Application created in Clerk Dashboard

Basic Authentication Setup

1. Get API Keys

1. Go to Clerk Dashboard
2. Select your application
3. Go to API Keys
4. Copy:
   • Publishable Key
   • Secret Key

2. Configure Environment Variables

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

3. Configure Redirect URLs

NEXT_PUBLIC_CLERK_SIGN_IN_URL="/auth/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/auth/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/dashboard/overview"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/dashboard/overview"

Organizations Setup

Enable Organizations

1. Go to Clerk Dashboard
2. Navigate to Configure → Organizations
3. Enable Organizations
4. Configure default roles:
   • Admin
   • Member
   • Viewer

Organization Features

• Multi-tenant workspaces
• Role-based access control
• Team management
• Organization switching

Webhook Setup

1. Create Webhook Endpoint

In Clerk Dashboard:

1. Go to Configure → Webhooks
2. Click Add Endpoint
3. Enter URL:
   • Development: http://localhost:3000/api/webhooks/clerk (use ngrok)
   • Production: https://yourdomain.com/api/webhooks/clerk

2. Subscribe to Events

Select these events:

• user.created
• user.updated
• user.deleted
• organization.created
• organization.updated
• organization.deleted
• organizationMembership.created
• organizationMembership.updated
• organizationMembership.deleted

3. Get Webhook Secret

1. Copy the Signing Secret (starts with whsec_)
2. Add to environment:

WEBHOOK_SECRET=whsec_...

4. Test Webhook Locally

Using ngrok:

ngrok http 3000

Use the ngrok URL in Clerk webhook endpoint.

Clerk Billing (Optional)

Enable Billing

1. Go to Billing Settings
2. Enable billing
3. Choose payment gateway:
   • Clerk development gateway (testing)
   • Stripe account (production)

Create Plans

1. Go to Plans
2. Select Plans for Organizations
3. Click Add Plan
4. Create plans (e.g., free, pro, team)
5. Set pricing and billing intervals
6. Toggle Publicly available

Add Features

1. Select a plan
2. In Features section, click Add Feature
3. Add features (e.g., premium_access, advanced_reports)

Usage in Code

Server-Side Checks

import { auth } from '@clerk/nextjs/server';

const hasPremiumAccess = await auth().has({ plan: 'pro' });
const hasFeature = await auth().has({ feature: 'premium_access' });

Client-Side Protection

import { Protect } from '@clerk/nextjs';

<Protect
  plan='pro'
  fallback={<p>Upgrade to Pro to access this feature.</p>}
>
  <PremiumContent />
</Protect>

Testing

Local Development

1. Use Clerk development keys
2. Test authentication flows
3. Test organization creation
4. Verify webhooks with ngrok

Production

1. Use production Clerk keys
2. Verify domain in Clerk
3. Set up production webhook
4. Test all authentication flows

Troubleshooting

Authentication Not Working

• Verify API keys are correct
• Check redirect URLs
• Verify domain in Clerk Dashboard
• Check browser console for errors

Webhooks Not Receiving Events

• Verify webhook URL is accessible
• Check webhook secret matches
• Review webhook logs in Clerk Dashboard
• Test with ngrok locally

Next Steps

• Stripe Connect Setup - Payment processing
• Resend Email Setup - Email functionality