Loading...
}
if (!isSignedIn) {
return
Dashboard
User ID: {userId}
Email: {user?.primaryEmailAddress?.emailAddress}
)
}
\`\`\`
**CRITICAL**:
- \`auth()\` is async in v6 (breaking change)
- Use \`auth()\` for lightweight checks
- Use \`currentUser()\` when you need full user object
---
## Cloudflare Workers Setup
### 1. Install Dependencies
\`\`\`bash
npm install @clerk/backend hono
\`\`\`
**Latest Versions**:
- @clerk/backend@2.17.2 (verified 2025-10-22)
- hono@4.10.1
### 2. Configure Environment Variables
Create \`.dev.vars\` for local development:
\`\`\`bash
CLERK_SECRET_KEY=sk_test_...
CLERK_PUBLISHABLE_KEY=pk_test_...
\`\`\`
**Production**: Use \`wrangler secret put CLERK_SECRET_KEY\`
### 3. Implement Token Verification
Create \`src/index.ts\`:
\`\`\`typescript
import { Hono } from 'hono'
import { verifyToken } from '@clerk/backend'
type Bindings = {
CLERK_SECRET_KEY: string
CLERK_PUBLISHABLE_KEY: string
}
type Variables = {
userId: string | null
sessionClaims: any | null
}
const app = new Hono<{ Bindings: Bindings; Variables: Variables }>()
// Middleware: Verify Clerk token
app.use('/api/*', async (c, next) => {
const authHeader = c.req.header('Authorization')
if (!authHeader) {
c.set('userId', null)
c.set('sessionClaims', null)
return next()
}
const token = authHeader.replace('Bearer ', '')
try {
const { data, error } = await verifyToken(token, {
secretKey: c.env.CLERK_SECRET_KEY,
// IMPORTANT: Set authorizedParties to prevent CSRF attacks
authorizedParties: ['https://yourdomain.com'],
})
if (error) {
console.error('Token verification failed:', error)
c.set('userId', null)
c.set('sessionClaims', null)
} else {
c.set('userId', data.sub)
c.set('sessionClaims', data)
}
} catch (err) {
console.error('Token verification error:', err)
c.set('userId', null)
c.set('sessionClaims', null)
}
return next()
})
// Protected route
app.get('/api/protected', (c) => {
const userId = c.get('userId')
if (!userId) {
return c.json({ error: 'Unauthorized' }, 401)
}
return c.json({
message: 'This is protected',
userId,
sessionClaims: c.get('sessionClaims'),
})
})
export default app
\`\`\`
**CRITICAL**:
- Always set \`authorizedParties\` to prevent CSRF attacks
- Use \`secretKey\`, not deprecated \`apiKey\`
- Source: https://clerk.com/docs/reference/backend/verify-token
---
## JWT Templates & Custom Claims
Clerk allows customizing JWT (JSON Web Token) structure using templates. This enables integration with third-party services, role-based access control, and multi-tenant applications.
### Quick Start: Create a JWT Template
**1. Navigate to Clerk Dashboard**:
- Go to **Sessions** page
- Click **Customize session token**
- Click **Create template**
**2. Define Template**:
```json
{
"user_id": "{{user.id}}",
"email": "{{user.primary_email_address}}",
"role": "{{user.public_metadata.role || 'user'}}"
}
```
**3. Use Template in Code**:
```typescript
// Frontend (React/Next.js)
const { getToken } = useAuth()
const token = await getToken({ template: 'my-template' })
// Backend (Cloudflare Workers)
const sessionClaims = c.get('sessionClaims')
const role = sessionClaims?.role
```
### Available Shortcodes
| Category | Shortcodes | Example |
|----------|-----------|---------|
| **User ID & Name** | `{{user.id}}`, `{{user.first_name}}`, `{{user.last_name}}`, `{{user.full_name}}` | `"John Doe"` |
| **Contact** | `{{user.primary_email_address}}`, `{{user.primary_phone_address}}` | `"john@example.com"` |
| **Profile** | `{{user.image_url}}`, `{{user.username}}`, `{{user.created_at}}` | `"https://..."` |
| **Verification** | `{{user.email_verified}}`, `{{user.phone_number_verified}}` | `true` |
| **Metadata** | `{{user.public_metadata}}`, `{{user.public_metadata.FIELD}}` | `{"role": "admin"}` |
| **Organization** | `org_id`, `org_slug`, `org_role` (in sessionClaims) | `"org:admin"` |
### Advanced Features
**String Interpolation**:
```json
{
"full_name": "{{user.last_name}} {{user.first_name}}",
"greeting": "Hello, {{user.first_name}}!"
}
```
**Conditional Fallbacks**:
```json
{
"role": "{{user.public_metadata.role || 'user'}}",
"age": "{{user.public_metadata.age || 18}}",
"verified": "{{user.email_verified || user.phone_number_verified}}"
}
```
**Nested Metadata with Dot Notation**:
```json
{
"interests": "{{user.public_metadata.profile.interests}}",
"department": "{{user.public_metadata.department}}"
}
```
### Default Claims (Auto-Included)
Every JWT includes these claims automatically (cannot be overridden):
```json
{
"azp": "http://localhost:3000", // Authorized party
"exp": 1639398300, // Expiration time
"iat": 1639398272, // Issued at
"iss": "https://your-app.clerk.accounts.dev", // Issuer
"jti": "10db7f531a90cb2faea4", // JWT ID
"nbf": 1639398220, // Not before
"sub": "user_1deJLArSTiWiF1YdsEWysnhJLLY" // User ID
}
```
### Size Limitation: 1.2KB for Custom Claims
**Problem**: Browser cookies limited to 4KB. Clerk's default claims consume ~2.8KB, leaving **1.2KB for custom claims**.
**⚠️ Development Note**: When testing custom claims in Vite dev mode, you may encounter **"431 Request Header Fields Too Large"** error. This is caused by Clerk's handshake token in the URL exceeding Vite's 8KB limit. See [Issue #11](#issue-11-431-request-header-fields-too-large-vite-dev-mode) for solution.
**Solution**:
```json
// ✅ GOOD: Minimal claims
{
"user_id": "{{user.id}}",
"email": "{{user.primary_email_address}}",
"role": "{{user.public_metadata.role}}"
}
// ❌ BAD: Exceeds limit
{
"bio": "{{user.public_metadata.bio}}", // 6KB field
"all_metadata": "{{user.public_metadata}}" // Entire object
}
```
**Best Practice**: Store large data in database, include only identifiers/roles in JWT.
### TypeScript Type Safety
Add global type declarations for auto-complete:
**Create `types/globals.d.ts`**:
```typescript
export {}
declare global {
interface CustomJwtSessionClaims {
metadata: {
role?: 'admin' | 'moderator' | 'user'
onboardingComplete?: boolean
organizationId?: string
}
}
}
```
### Common Use Cases
**Role-Based Access Control**:
```json
{
"email": "{{user.primary_email_address}}",
"role": "{{user.public_metadata.role || 'user'}}",
"permissions": "{{user.public_metadata.permissions}}"
}
```
**Multi-Tenant Applications**:
```json
{
"user_id": "{{user.id}}",
"org_id": "{{user.public_metadata.org_id}}",
"org_role": "{{user.public_metadata.org_role}}"
}
```
**Supabase Integration**:
```json
{
"email": "{{user.primary_email_address}}",
"app_metadata": {
"provider": "clerk"
},
"user_metadata": {
"full_name": "{{user.full_name}}"
}
}
```
### See Also
- **Complete Reference**: See `references/jwt-claims-guide.md` for comprehensive documentation
- **Template Examples**: See `templates/jwt/` directory for working examples
- **TypeScript Types**: See `templates/typescript/custom-jwt-types.d.ts`
- **Official Docs**: https://clerk.com/docs/guides/sessions/jwt-templates
---
## Testing
Clerk provides comprehensive testing tools for local development and CI/CD pipelines.
### Quick Start: Test Credentials
**Test Emails** (no emails sent, fixed OTP):
```
john+clerk_test@example.com
jane+clerk_test@gmail.com
```
**Test Phone Numbers** (no SMS sent, fixed OTP):
```
+12015550100
+19735550133
```
**Fixed OTP Code**: `424242` (works for all test credentials)
### Generate Session Tokens
For testing API endpoints, generate valid session tokens (60-second lifetime):
```bash
# Using the provided script
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js
# Create new test user
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js --create-user
# Auto-refresh token every 50 seconds
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js --refresh
```
**Manual Flow**:
1. Create user: `POST /v1/users`
2. Create session: `POST /v1/sessions`
3. Generate token: `POST /v1/sessions/{session_id}/tokens`
4. Use in header: `Authorization: Bearer