Back to Integrations
Clerk logo

Clerk

Drop-in authentication and user management for InsForge applications.

WebsiteDocumentation

Overview

Clerk is an authentication and user management platform that provides pre-built UI components and APIs for sign-up, sign-in, and user profiles. This guide shows how to integrate Clerk with InsForge using Clerk's JWT Templates feature. Clerk signs tokens with InsForge's JWT secret, so InsForge accepts them natively.

  • Live Demo — A sample CRM app using Clerk authentication with InsForge
  • Source Code — GitHub repository for the sample app

Prerequisites

  • An InsForge project (self-hosted or cloud)
  • A Clerk account and application
  • Your InsForge project's JWT Secret (found in the InsForge dashboard under project settings)

Step 1: Set Up Your InsForge Project

Create a new project or link an existing one:

bash
# Create a new project
npx @insforge/cli create

# Or link an existing project
npx @insforge/cli link --project-id <your-project-id>

Then note down the URL, Anon Key, and JWT Secret from the InsForge dashboard (project settings).

Step 2: Create a JWT Template in Clerk

  1. Go to your Clerk Dashboard
  2. Navigate to Configure > JWT Templates
  3. Click New template and select Blank
  4. Name it insforge
  5. Set the Signing algorithm to HS256
  6. Paste your InsForge JWT Secret into the Signing key field
  7. Set the token claims to:
json
{
  "role": "authenticated",
  "aud": "insforge-api"
}

sub and iss are reserved claims in Clerk and are automatically included — do not add them manually.

  1. Save the template

Step 3: Set Up Your Application

Fill in .env (or .env.local for Next.js):

env
VITE_INSFORGE_BASE_URL=...
VITE_INSFORGE_ANON_KEY=...               # optional
VITE_CLERK_PUBLISHABLE_KEY=pk_...        # required

Step 4: Set Up InsForge Integration

Ask your agent to complete the following steps:

1. Set up the InsForge client with Clerk

text
Set up the InsForge client with Clerk authentication. I'm using React with Vite.

This initializes the InsForge client using getToken({ template: 'insforge' }) from Clerk's useAuth() hook, passed as an async edgeFunctionToken.

2. Create the database schema

text
Create a todos table with RLS. Columns: id, user_id, title, is_complete, created_at. Users should only be able to access their own todos.

This creates the requesting_user_id() helper function (since Clerk user IDs are strings, not UUIDs) and a todos table with Row Level Security policies.

3. Build the todo list page

text
Build a todo list page with full CRUD — create, read, update, and delete todos.

This creates a page that uses the InsForge client to manage todos. RLS ensures users only see their own data.