Agent Skills: Clerk Knowledge Patch

Clerk Knowledge Patch

Claude's baseline knowledge covers Clerk through Core 2 (@clerk/nextjs v5, @clerk/clerk-react). This patch adds Core 3 changes (@clerk/nextjs v6+, @clerk/react v1+), Go SDK v2, Python backend SDK, and new features through early 2025.

Index

| Topic | Reference | Key Content | |-------|-----------|-------------| | Components | references/components.md | <Show> (replaces SignedIn/SignedOut), UserAvatar, Waitlist, billing components, UserButton menu customization, UNSAFE_PortalProvider | | Authentication Flows | references/authentication-flows.md | Core 3 custom flow API (method chaining), reverification, session tasks, signUpIfMissing, Errors<T> type, session token v2 claims | | Middleware & Backend | references/middleware-backend.md | isAuthenticated, async clerkClient(), machine token auth, Frontend API proxy, dynamic keys, organizationSyncOptions | | Organizations & Permissions | references/organizations.md | Role Sets, system permissions, org slug URL patterns | | Clerk Elements | references/clerk-elements.md | Headless UI primitives (@clerk/elements), sign-in/sign-up anatomy, shadcn/ui CLI | | Billing | references/billing.md | Custom checkout (useCheckout + PaymentElement), billing hooks, backend/client-side billing APIs, B2B billing, free trials | | Go SDK v2 | references/go-sdk.md | Package structure, sub-package imports, HTTP middleware, JWT verification, reverification, testing patterns | | Python SDK | references/python-sdk.md | clerk-backend-api package, _async suffix convention, request authentication | | Integrations & Utilities | references/integrations-utilities.md | MCP tools, OAuth provider (IdP), TanStack Start, React Router, Astro, Chrome Extension, getToken, ClerkOfflineError, Web3, enterprise_sso |

Core 3 Migration Essentials

Package Rename

# React SDK renamed
npm install @clerk/react # was @clerk/clerk-react
# Next.js unchanged
npm install @clerk/nextjs # still @clerk/nextjs (now v6+)

<Show> Replaces <SignedIn> / <SignedOut>

import { Show, SignInButton, UserButton } from '@clerk/react'

<Show when="signed-in">
  <UserButton />
</Show>
<Show when="signed-out">
  <SignInButton />
</Show>

// Authorization checks
<Show when={{ permission: 'org:invoices:create' }} fallback={<p>No access</p>}>
  <InvoiceForm />
</Show>
<Show when={{ feature: 'premium_access' }} fallback={<p>Upgrade</p>}>
  <PremiumFeature />
</Show>
<Show when={(has) => has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })}>
  <SettingsPage />
</Show>

Full when type: 'signed-in' | 'signed-out' | { feature: string } | { permission: string } | { plan: string } | { role: string } | (has) => boolean

Key API Changes Quick Reference

| Core 2 | Core 3 | Notes | |--------|--------|-------| | <SignedIn> / <SignedOut> | <Show when="signed-in"> | Unified control component | | @clerk/clerk-react | @clerk/react | Package rename | | if (!userId) | if (!isAuthenticated) | auth() returns isAuthenticated boolean | | const client = clerkClient | const client = await clerkClient() | Now async function | | signUp.create() → prepareVerification() → attemptVerification() → setActive() | signUp.password() → verifications.sendEmailCode() → verifications.verifyEmailCode() → finalize() | Method chaining API | | clerkJSVariant: 'headless' | prefetchUI={false} | On ClerkProvider | | saml strategy | enterprise_sso | Supports both SAML + OIDC | | user.samlAccounts | user.enterpriseAccounts | Property rename | | clerkClient.samlConnections | clerkClient.enterpriseConnections | Backend rename |

ClerkProvider Auto-detects Key

// No publishableKey prop needed — reads from env vars automatically:
// NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY (Next.js)
// VITE_CLERK_PUBLISHABLE_KEY (Vite)
// CLERK_PUBLISHABLE_KEY (general)
<ClerkProvider>
  <App />
</ClerkProvider>

Auth Pattern (Server-side)

import { auth } from '@clerk/nextjs/server'

// Core 3 pattern
const { isAuthenticated, userId, redirectToSignIn } = await auth()
if (!isAuthenticated) return redirectToSignIn()

// clerkClient is now async
const client = await clerkClient()
const user = await client.users.getUser(userId)

Machine Token Authentication

// Middleware — protect routes by token type
export default clerkMiddleware(async (auth, req) => {
  if (isApiRoute(req)) await auth.protect({ token: 'api_key' })
  if (isM2MRoute(req)) await auth.protect({ token: 'm2m_token' })
  if (isOAuthRoute(req)) await auth.protect({ token: 'oauth_token' })
})

// Route handler — acceptsToken parameter
const { userId } = await auth({ acceptsToken: 'oauth_token' })

Standalone getToken()

import { getToken } from '@clerk/nextjs' // or @clerk/react, @clerk/vue

// Works outside React — in axios interceptors, React Query, vanilla JS
axios.interceptors.request.use(async (config) => {
  const token = await getToken()
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

Throws ClerkOfflineError when offline (instead of returning null). Import from @clerk/react/errors.

Types Subpath Export

import type { UserResource, OrganizationResource } from '@clerk/react/types'
// Also: @clerk/nextjs/types, @clerk/vue/types, etc.

Custom Flow API (Core 3 Summary)

Old pattern: signUp.create() → prepareEmailAddressVerification() → attemptEmailAddressVerification() → setActive()

New pattern uses method chaining:

// Sign-up
const { signUp, errors, fetchStatus } = useSignUp()
await signUp.password({ emailAddress, password })
await signUp.verifications.sendEmailCode()
await signUp.verifications.verifyEmailCode({ code })
if (signUp.status === 'complete') await signUp.finalize({ navigate: ({ decorateUrl }) => { /* ... */ } })

// Sign-in
const { signIn, errors, fetchStatus } = useSignIn()
await signIn.create({ identifier: emailAddress })
await signIn.emailCode.sendCode()
await signIn.emailCode.verifyCode({ code })
if (signIn.status === 'complete') await signIn.finalize({ navigate: ({ decorateUrl }) => { /* ... */ } })

Field-level errors: errors.fields.emailAddress, errors.fields.password, errors.fields.code. Loading: fetchStatus === 'fetching'.

Reverification (Step-up Auth)

// Server action
import { auth, reverificationError } from '@clerk/nextjs/server'
export const sensitiveAction = async () => {
  const { has } = await auth.protect()
  if (!has({ reverification: 'strict' })) return reverificationError('strict')
  // Presets: 'strict_mfa' | 'strict' (10m) | 'moderate' (1h) | 'lax'
}

// Client — wraps action, auto-shows verification modal
import { useReverification } from '@clerk/nextjs'
const perform = useReverification(sensitiveAction)
const result = await perform() // null if user cancelled

Session Tasks (Pending Sessions)

Three states: signed-in | pending | signed-out. Pending = authenticated but tasks incomplete (choose org, reset password, setup MFA).

import { TaskChooseOrganization, TaskResetPassword, TaskSetupMFA } from '@clerk/nextjs'

// In middleware — redirect pending users
const { isAuthenticated, sessionStatus } = await auth()
if (!isAuthenticated && sessionStatus === 'pending') {
  // redirect to /session-tasks
}

// Access pending user data
const { userId } = await auth({ treatPendingAsSignedOut: false })

Billing Quick Reference

// Components (PricingTable from main, rest from /experimental)
import { PricingTable } from '@clerk/nextjs'
import { CheckoutButton, useCheckout, usePlans, useSubscription } from '@clerk/nextjs/experimental'

<PricingTable />                                    // works signed-in or signed-out
<PricingTable for="organization" />                 // org-level plans
<CheckoutButton planId="cplan_xxx" planPeriod="month" for="user" />  // must be in <Show when="signed-in">

// Hooks (all experimental) — shared interface: { data, isLoading, hasNextPage, fetchNext, revalidate }
const { data: plans } = usePlans({ for: 'user' })
const { data: subscription } = useSubscription({ for: 'organization' })

// Backend
const client = await clerkClient()
const sub = await client.billing.getUserBillingSubscription('user_123')
await client.billing.cancelSubscriptionItem('subi_123', { endNow: true })

B2B gotcha: has({ permission: 'org:teams:manage' }) returns false if the org's Plan doesn't include the "teams" Feature, even if the user has the permission.

Go SDK v2 Quick Reference

import "github.com/clerk/clerk-sdk-go/v2"           // was github.com/clerkinc/clerk-sdk-go
import "github.com/clerk/clerk-sdk-go/v2/user"       // sub-packages per resource
import clerkhttp "github.com/clerk/clerk-sdk-go/v2/http"

clerk.SetKey("sk_live_XXX")
// Pointer helpers: clerk.String(), clerk.Bool(), clerk.Int64()
// Header-only auth (no cookies): clerkhttp.RequireHeaderAuthorization()(handler)
// Claims: claims, ok := clerk.SessionClaimsFromContext(r.Context())

Python SDK Quick Reference

# Package: clerk-backend-api (NOT clerk-python)
from clerk_backend_api import Clerk

with Clerk(bearer_auth="sk_live_xxx") as clerk:
    user = clerk.users.get(user_id="user_123")
# Async uses _async suffix: await clerk.users.get_async(user_id="user_123")