A technical implementation skill for Clerk authentication that addresses Next.js 16 security patterns, API breaking changes, and critical error prevention.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install clerk-auth
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install clerk-auth using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Clerk Auth?
This skill provides an advanced framework for implementing Clerk authentication, specifically optimized for the latest framework updates and security standards. It focuses on the transition to Next.js 16 and the mandatory use of proxy.ts to address historical middleware vulnerabilities. By utilizing Openclaw Skills for your authentication layer, you gain immediate access to battle-tested patterns for API version 2025-11-10, ensuring your application remains resilient against documented breaking changes and common integration errors.
Beyond basic setup, the skill handles complex scenarios like networkless JWT verification for high-availability requirements and cross-platform user type consistency. It serves as a comprehensive developer advocate tool for managing identity, organization-level authorization, and secure programmatic access via the latest API Keys beta features.
Clerk Auth Use Cases
- Deploying secure authentication in Next.js 16 applications using the proxy.ts middleware pattern.
- Implementing self-service API Key management for users and organizations using zero-code UI components.
- Resolving 431 Request Header Too Large errors in Vite development environments with custom JWT claims.
- Verifying Clerk webhooks for automated user and organization synchronization.
- Conducting E2E testing with Playwright using fixed OTP codes and the @clerk/testing package.
How Clerk Auth Works
- The skill initializes the Clerk environment by validating required secret keys and environment variables.
- It implements the clerkMiddleware inside the proxy.ts file to handle route protection and session management.
- The async auth helper is utilized in server components to retrieve validated user and session identifiers.
- Custom JWT templates are processed, ensuring metadata remains within the 1.2KB browser cookie limit.
- Programmatic access is managed through the API Keys beta, distinguishing between session tokens and API tokens in the middleware.
- For production reliability, the system implements jwtKey for offline token verification during potential cloud service outages.
Clerk Auth Setup
To integrate this skill into your project, install the required dependencies and configure the middleware structure:
npm install @clerk/nextjs@^6.36.7 @clerk/backend@^2.29.2 @clerk/testing@^1.13.26
For Next.js 16+, ensure your middleware is named correctly and initialized:
// src/proxy.ts
import { clerkMiddleware } from '@clerk/nextjs/server';
export default clerkMiddleware();
export const config = {
matcher: ['/((?!_next|[^?]*\\.(?:html?|css|js)).*)', '/(api|trpc)(.*)'],
};
Ensure your environment variables are set in .env.local using the NEXT_PUBLIC_ prefix for the publishable key and the CLERK_SECRET_KEY for backend operations.
Clerk Auth Data Schema & Taxonomy
The skill organizes authentication data and metadata through the following taxonomy:
| Data Category | Key Properties | Description |
|---|---|---|
| Session Metadata | userId, sessionId, tokenType |
Core identifiers for the active request context. |
| JWT Custom Claims | public_metadata, private_metadata |
User-defined data fields (Must be < 1.2KB). |
| Organization Context | org_id, org_slug, org_role |
Multi-tenant identifiers for RBAC. |
| API Key Object | key_id, last_used_at, scope |
Metadata for programmatic access tokens. |
| Webhook Payload | type, data, object |
Structured events for backend synchronization. |
Clerk Auth Advanced Features
- Local JWT verification using jwtKey to maintain uptime during Google Cloud Platform or Clerk service disruptions.
- Automated credential stuffing defense with forced secondary authentication for unrecognized devices.
- Organization synchronization patterns that map specific URL slugs to active organization contexts.
- PKCE support for custom OIDC providers in native and mobile application environments.
- Automatic cache invalidation for Next.js 16 during sign-out flows using Openclaw Skills patterns.
SKILL.md
Loading
Related Openclaw Skills
Claude Agent SDK
A comprehensive toolkit for building autonomous AI agents with Claude, featuring robust error prevention and structured JSON outputs.
CI/CD Pipeline Generator
A specialized tool for generating production-ready CI/CD configurations for GitHub Actions, GitLab CI, and CircleCI to automate testing and deployment.
Breadth Chart Analyst
A specialized technical analysis skill for interpreting market breadth and uptrend ratio charts to generate strategic positioning and tactical trading signals.
Brand Analyzer
A comprehensive framework for analyzing brand identity, conducting professional audits, and generating actionable brand guidelines.
CLI Developer
A senior engineering skill for building intuitive, high-performance command-line tools across multiple ecosystems.
Codebase Documenter
An automated documentation engine that generates beginner-friendly READMEs, architecture guides, and API documentation for any codebase.
Featured*
