Moai Platform Clerk

Clerk Modern Authentication Specialist

Modern authentication platform with WebAuthn, passkeys, passwordless flows, beautiful pre-built UI components, and multi-tenant organization support.

Quick Reference (30 seconds)

Clerk Core Capabilities:

• WebAuthn and Passkeys: First-class biometric and hardware key support
• Passwordless: Email magic links, SMS OTP, email OTP
• Pre-built UI: SignIn, SignUp, UserButton, OrganizationSwitcher components
• Organizations: Multi-tenant team management with RBAC
• Multi-Platform: React, Next.js, Vue, React Native, Node.js SDKs

Context7 Access:

• Library: /clerk/clerk-docs
• Resolution: Use resolve-library-id with "clerk" then get-library-docs

Quick Decision Criteria:

• Need WebAuthn and passkeys? Clerk is ideal
• Need beautiful pre-built auth UI? Clerk provides ready components
• Need passwordless authentication? Clerk supports all methods
• Need multi-tenant organizations? Clerk Organizations feature
• Need React/Next.js integration? Clerk has first-class support

Implementation Guide

WebAuthn and Passkey Implementation

WebAuthn Configuration:

Clerk provides first-class WebAuthn support enabling passwordless authentication with biometrics and hardware security keys.

Step 1: Enable WebAuthn in Clerk Dashboard under User and Authentication Step 2: Configure passkey requirements (required, optional, or disabled) Step 3: Set verification requirements for passkey registration Step 4: Implement passkey UI using Clerk components or custom flow

Passkey User Experience:

• Registration flow prompts for biometric or security key
• Login flow automatically detects available passkeys
• Fallback to password if passkeys unavailable
• Cross-device passkey support with FIDO Alliance standards

Passkey Registration Flow:

User clicks "Add Passkey" button in account settings Clerk prompts for device biometric or security key Browser WebAuthn API handles credential creation Passkey stored securely in Clerk backend User can manage multiple passkeys per account

Passkey Login Flow:

User navigates to sign-in page Clerk detects available passkeys for user User authenticates with biometric or security key Session created automatically upon successful verification

Passwordless Authentication

Email Magic Links:

Clerk sends secure magic links for passwordless sign-in with customizable email templates.

Configuration Steps:

Step 1: Enable Email magic link in Clerk Dashboard Step 2: Customize email template with branding Step 3: Configure link expiration time Step 4: Set redirect URL after successful authentication

Magic Link Features:

• Customizable email templates with branding
• Configurable expiration times
• Secure one-time use tokens
• Automatic session creation on click

SMS One-Time Passwords:

Step 1: Enable SMS authentication in Dashboard Step 2: Configure phone number verification requirements Step 3: Set OTP expiration and retry limits Step 4: Customize SMS message template

Email One-Time Passwords:

Step 1: Enable Email OTP in authentication settings Step 2: Configure code length (6 or 8 digits) Step 3: Set code expiration time Step 4: Customize email template

Pre-built UI Components

Available Components:

SignIn Component: Complete sign-in form with social and email options SignUp Component: Registration form with verification UserButton Component: User avatar dropdown with profile management OrganizationSwitcher Component: Organization selection dropdown UserProfile Component: Full user profile management CreateOrganization Component: Organization creation flow

React Integration:

Install @clerk/clerk-react package Wrap application with ClerkProvider Use components directly in JSX Customize appearance via theme prop

Next.js Integration:

Install @clerk/nextjs package Add Clerk middleware for route protection Use components in pages and layouts Configure environment variables for API keys

Component Customization:

• Theme customization via appearance prop
• Custom CSS with provided class names
• Override individual elements
• Dark mode support built-in

Organization Management (Multi-Tenancy)

Organization Features:

• Create and manage organizations programmatically
• Invite users via email with customizable invitations
• Role-based permissions (admin, member, custom roles)
• Organization switching for users with multiple memberships
• Domain verification for automatic organization membership

Creating Organizations:

Step 1: Enable Organizations feature in Dashboard Step 2: Configure default roles and permissions Step 3: Set invitation email templates Step 4: Implement CreateOrganization component

Invitation System:

Step 1: Admin initiates invitation via dashboard or API Step 2: Invitee receives customizable email invitation Step 3: Invitee clicks link and completes signup or signin Step 4: Automatic organization membership upon completion

Role-Based Access Control:

Default Roles:

• org:admin: Full organization management
• org:member: Standard member access

Custom Roles:

• Define custom roles in Dashboard
• Assign permissions to roles
• Check permissions in application code

Domain Verification:

Organizations can claim domains for automatic membership Users with verified email from claimed domain auto-join Reduces friction for enterprise onboarding

Session Management

Session Features:

• Automatic token refresh
• Multi-device session tracking
• Session revocation capability
• Configurable session duration

Session Configuration:

Step 1: Configure session lifetime in Dashboard Step 2: Set multi-session or single-session mode Step 3: Configure token refresh behavior Step 4: Enable session activity tracking

Token Management:

• Access tokens for API authentication
• Session tokens for frontend state
• Automatic refresh before expiration
• Secure httpOnly cookie storage option

Multi-Platform SDK Support

Supported Platforms:

React: @clerk/clerk-react Next.js: @clerk/nextjs with middleware support Vue: @clerk/vue (community maintained) React Native: @clerk/clerk-expo Node.js: @clerk/clerk-sdk-node Express: @clerk/express Fastify: @clerk/fastify

Next.js Middleware:

Clerk middleware protects routes at Edge Configure public and protected route patterns Automatic redirect to sign-in for unauthenticated users Access user session in middleware for custom logic

Backend Verification:

Node.js SDK verifies session tokens Extract user ID and organization from token Implement authorization logic in API routes Webhook signature verification for events

Advanced Patterns

Custom Authentication Flows

Building Custom Sign-In:

Use useSignIn hook for programmatic control Implement multi-step verification flows Handle errors with custom UI Support social OAuth alongside email

Building Custom Sign-Up:

Use useSignUp hook for registration logic Implement progressive profiling Custom verification code entry UI Handle optional vs required fields

Headless Mode:

Full control over UI while using Clerk backend Access all functionality via hooks Implement completely custom designs Maintain security without pre-built components

Webhook Integration

Available Webhook Events:

user.created: New user registration completed user.updated: User profile changes user.deleted: User account deleted session.created: New session started session.ended: Session terminated organization.created: New organization created organization.membership.created: User joined organization

Webhook Configuration:

Step 1: Add webhook endpoint URL in Dashboard Step 2: Select events to subscribe Step 3: Copy signing secret for verification Step 4: Implement signature verification in endpoint

Webhook Security:

Verify webhook signatures using svix library Check timestamp to prevent replay attacks Return 200 status for successful processing Implement idempotency for duplicate handling

JWT Customization

Custom Claims:

Add custom claims to session tokens Include organization metadata Add user roles and permissions Configure claim templates in Dashboard

JWT Templates:

Create multiple JWT templates for different services Configure issuer and audience Set expiration times Add conditional claims based on user attributes

Integration Patterns

Clerk with Database Providers:

Clerk with Convex:

• Use Clerk JWT verification in Convex functions
• Sync user data via webhooks
• Implement organization-based access control

Clerk with Supabase:

• Configure Clerk JWT in Supabase settings
• Map Clerk claims to RLS policies
• Use organization ID for multi-tenant isolation

Clerk with Prisma:

• Sync user ID from Clerk to database
• Store additional user data with Clerk user ID as foreign key
• Handle user lifecycle via webhooks

Deployment Platforms:

Vercel: Native integration with Edge Middleware Railway: Environment variable configuration Netlify: Serverless function integration AWS Lambda: SDK support for serverless

Security Best Practices

Token Security:

• Use short-lived access tokens
• Enable automatic token refresh
• Store tokens securely in httpOnly cookies
• Validate tokens on backend for all requests

Rate Limiting:

• Clerk implements built-in rate limiting
• Configure custom limits per organization
• Monitor authentication attempts
• Alert on suspicious patterns

Multi-Factor Authentication:

Enable MFA in Dashboard settings Support authenticator apps (TOTP) Backup codes for account recovery SMS as secondary verification option

Account Protection:

• Enable device verification for new logins
• Configure suspicious activity detection
• Implement session activity monitoring
• Provide users with security notifications

Resources

Context7 Documentation Access:

Library Resolution: Use resolve-library-id with "clerk" Documentation Fetch: Use get-library-docs with resolved ID

API Documentation:

Backend API: https://clerk.com/docs/reference/backend-api Frontend SDK: https://clerk.com/docs/references/react/overview Next.js SDK: https://clerk.com/docs/references/nextjs/overview Webhooks: https://clerk.com/docs/integrations/webhooks

Works Well With:

• moai-platform-auth0: Alternative enterprise SSO solution
• moai-platform-supabase: Supabase authentication integration
• moai-platform-vercel: Vercel deployment with Clerk
• moai-platform-firebase-auth: Firebase authentication comparison
• moai-lang-typescript: TypeScript development patterns
• moai-domain-frontend: React and Next.js integration
• moai-quality-security: Security validation and OWASP compliance

Status: Production Ready Generated with: MoAI-ADK Skill Factory v1.0 Last Updated: 2025-12-07 Provider Coverage: Clerk Authentication Platform