clerk-nextjs-patterns

Protect Next.js API routes with Clerk middleware by defining route matchers to enforce access consistently. Choose a public-first or protected-first matching strategy to block unauthorized mutations across your application.

Use Clerk auth primitives like `await auth()` in Server Actions to block unauthorized mutations and enforce permissions. Return consistent 401 or 403 HTTP codes based on the specific authentication and authorization state.

Auth-safe caching in Next.js requires building user-scoped or org-scoped cache keys using userId or orgId. You must revalidate cache tags after updates to prevent cross-user data leaks in Clerk authenticated sessions.

Generate custom JWT tokens for external APIs like Supabase or Hasura using Clerk's `getToken()` workflow. This allows secure access to external services by passing valid authentication tokens from your Next.js application.

Mixing Clerk server and client auth causes issues because Server Components require `await auth()` while Client Components use Clerk hooks. Separating these patterns correctly prevents asynchronous context errors and authentication failures.

Handle 401 and 403 errors differently in protected Next.js API routes to distinguish authentication failures from permission issues. Return 401 for missing Clerk auth and 403 when authenticated users lack specific permissions.