---
name: clerk-cloudflare-auth
description: Add Clerk authentication to Cloudflare Pages or Workers apps with protected APIs, session-aware UI, and optional application-side user mapping.
license: MIT
tags: [clerk, cloudflare, auth, pages, workers, vite, d1]
agents: [claude-code, codex, autojack]
category: auth
metadata:
version: "1.1.0"
capabilities:
network: true
filesystem: readwrite
tools: [Bash, Read, Edit]
requires-secrets:
- name: CLERK_SECRET_KEY
description: Server-side Clerk credential, configured through the deployment platform.
required: true
resources:
- path: story.md
type: file
---Clerk + Cloudflare Auth
Use this skill when a Cloudflare Pages or Workers application needs Clerk login,
session-aware UI, protected API routes, account records, or billing-linked user
mapping. Clerk should own identity; the application should own its domain data
and any billing records.
Secret boundary
Keep provider values in the platform's environment-variable or secret manager.
Do not commit them, paste them into chat, or invent a local credential-store
format. A typical deployment needs these names:
CLERK_SECRET_KEY=<managed server secret>
VITE_CLERK_PUBLISHABLE_KEY=<managed build variable>The publishable key is intended for the browser but should still be supplied by
the build environment. CLERK_SECRET_KEY belongs only in server-side runtime
configuration. For local development, use ignored environment files and do not
read or print their contents unless the user explicitly asks.
Integration shape
- Inspect the application: framework, Pages Functions or Workers entry point, existing session model, public/protected routes, and application records keyed to users or accounts.
- Add Clerk's framework package in the client and Clerk's server package where the edge runtime verifies tokens. Follow current official Clerk and Cloudflare documentation for the package-specific initialization API.
- Initialize the client from
VITE_CLERK_PUBLISHABLE_KEY. Render a clear signed-out fallback if it is absent in a local build. - Verify the session token at every protected Pages Function or Worker route; never treat client-side visibility as authorization.
- Map the verified Clerk user or organization ID to D1/application records only where the product needs internal data. Keep Stripe customer and subscription truth in the billing layer rather than duplicating it in identity claims.
Frontend rules
- Prefer the framework's reactive Clerk APIs over polling global state.
- Request a fresh token immediately before authenticated API calls.
- Guard against a late anonymous response replacing a newer signed-in state.
- Configure Clerk appearance through its supported configuration object, not brittle global CSS overrides.
- Keep static marketing pages static; add identity only where it is needed.
Edge authorization
At the server boundary, extract and verify the Clerk session token using the
official backend SDK. Return 401 for a missing/invalid session and 403 for
an authenticated user without the required application entitlement. Make route
policy explicit so public webhooks and health endpoints do not accidentally
inherit account-only checks.
Verification
Before deployment, test:
- Signed-out visitors can reach public pages and cannot call protected APIs.
- A signed-in test user receives the expected account data.
- Expired or malformed tokens are rejected by the edge route.
- Local and preview builds receive the appropriate Clerk environment values.
- Any D1 user mapping is idempotent and uses the verified Clerk identifier.
Use Cloudflare Commerce Deploy for
provider configuration and Stripe Commerce Checkout
when authentication gates paid product access.