clerk

Clerk Best Practices

Integrating Clerk requires a security-first mindset. Authentication is a primary attack surface; therefore, all Clerk integrations MUST adhere to the strictest security standards. This guide provides actionable, opinionated best practices to ensure your application's identity layer is robust and future-proof.

1. Security Best Practices

1.1. Enforce Authorization Code Flow with PKCE

NEVER use the implicit grant flow. RFC 9700 explicitly deprecates it due to inherent security weaknesses. Always use the Authorization Code Flow with Proof Key for Code Exchange (PKCE). Clerk's client-side SDKs handle PKCE automatically when correctly configured.

❌ BAD: Relying on deprecated flows (e.g., implicit grant)

// Avoid configuring Clerk in ways that force implicit grants
// (e.g., older SDK versions or misconfigurations)
// Ensure your Clerk application settings are configured for PKCE.

✅ GOOD: Utilize Clerk's Authorization Code Flow with PKCE (default for modern SDKs)

// Clerk's modern SDKs (v5.x+) use PKCE by default.
// Ensure your Clerk application is configured to require PKCE.
// Example: Initializing Clerk in a Next.js app
import { ClerkProvider } from '@clerk/nextjs';

function MyApp({ Component, pageProps }) {
  return (
    <ClerkProvider {...pageProps}>
      <Component {...pageProps} />
    </ClerkProvider>
  );
}

1.2. Centralize Authentication Logic

All authentication and authorization checks MUST occur server-side and be handled by a centralized, security-vetted library (Clerk's backend SDKs). Never perform critical authentication decisions solely on the client.

❌ BAD: Client-side authorization decisions

// In a React component:
if (clerk.user.publicMetadata.role === 'admin') {
  // Render admin-only content
}
// This is easily bypassed by manipulating client-side state.

✅ GOOD: Server-side authorization with Clerk's backend SDKs

// In a Next.js API route or server component:
import { getAuth } from '@clerk/nextjs/server';
import { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { userId, orgRole } = getAuth(req);

  if (!userId) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  if (orgRole !== 'admin') {
    return res.status(403).json({ error: 'Forbidden' });
  }

  // Proceed with admin-only logic
  res.status(200).json({ message: 'Welcome, admin!' });
}