Clerk security: what Clerk handles and what your application still has to check
Clerk runs sign-in and issues sessions.
Your application decides what each signed-in person may read and change. This guide covers the Clerk helpers and settings that sit on that line: middleware and server-side checks, authorised parties, session settings, token claims, metadata, organisation roles, webhooks and the separation of test and live keys, with each fact credited to the page that states it. The worksheet at the end records all of them for your own application.
In this guide
Clerk integration worksheet
Paste the worksheet into a document or spreadsheet and keep one copy for each application that uses Clerk. Part 1 shows it filled in for an invented freight portal; Part 2 is the empty form.
How to use itHide the instructions
Parts A to I record test and live key separation, middleware visibility against the checks inside each route, redirect URLs and domains, session and sign-up settings, the token claims your server reads, metadata, organisation roles, webhook verification and SDK versions against the advisory log. Every part is a reading of your own Clerk Dashboard, hosting settings, code and lockfile. Its screen and tab names come from Clerk's pages as read on 14 November 2026.
clerk.txt
Introduction11 lines
Part 1. Worked example97 lines
Part 2. Blank worksheet67 lines
Whole template182 lines
CLERK INTEGRATION WORKSHEET
One worksheet per application that uses Clerk. Every part is a reading: of the Clerk Dashboard, of your hosting provider's list of environment variables (names and scopes; the only values read are the Publishable Key's prefix and the sign-in and redirect paths, which are not secrets), of your own code and lockfile, and of your own pages in an ordinary browser visit. Nothing in it changes a setting, rotates or reveals a key, signs in as one of your application's users, or sends test requests to Clerk's services or to anyone else's system.
RULES FOR FILLING IT IN
1. Names, never values. Never write a Secret Key, webhook signing secret, JWT key, session token or password into this worksheet, and never open a screen or file to reveal one. Clerk's clerkMiddleware() reference says the API keys page shows a Secret Key's full value only once, when it is added, so Part A records each key by its name and last-used time instead.
2. Publishable Keys are recorded by prefix only: pk_test_ or pk_live_. Clerk's rotate keys guide says the Publishable Key is safe to expose on the frontend; the prefix is all this worksheet needs.
3. A Secret Key is recorded by the variable that holds it, the environment scope it is set for, the key name it came from and who confirmed that. Where a file such as an .env file can hold a key, record only whether the key's variable name is present, using a search that reports only whether the name appears, never by opening the file, so the value is not shown on screen.
4. A webhook's signing secret is recorded by the name of the variable that holds it (CLERK_WEBHOOK_SIGNING_SECRET, the variable Clerk's environment variables page says verifyWebhook() reads) and nothing else. Clerk's webhooks overview says the signing secret is found by selecting the endpoint on the Webhooks page, so Part H reads the endpoint list without selecting an endpoint.
5. Do not decode, copy or paste a real user's session token. The claims in Part E come from your code and the Clerk Dashboard.
6. A screen or tab appears only where a Clerk page cited here names it, and that page is given beside it. Rows with no such page describe what to read and leave finding it to you.
7. Every finding is a note for the person who owns the setting or the code. Changing a setting, rotating a key, revoking sessions, deleting an endpoint or upgrading a package is a separate decision, recorded on the decision line.
==================================================
PART 1. WORKED EXAMPLE
Part 1 is invented from start to finish, including the business, its staff, its domains, its code and its records, and no real system was touched to write it.
Application: Kerrigan Freight Portal, an invented quoting portal where each customer company is a Clerk organisation
Framework: Next.js App Router with @clerk/nextjs
Production: app.kerriganfreight.example Staging: staging.kerriganfreight.example Previews: the host's own preview domain
Reviewed by: the operations manager, with the lead developer, on 14 November 2026
A. INSTANCES, KEYS AND ENVIRONMENTS (test versus live)
Where to look: the app and environment selector at the top left of the Clerk Dashboard, then the API keys page in the sidenav, where Secret keys are listed and each shows when it was last used (Clerk's rotate keys guide). Keys with an IP allowlist show the number of entries next to their name (Clerk's IP allowlist page). Your hosting provider's environment variables, by name and scope only. The Publishable Key prefix, from the variable list or your own page source.
Record per environment: environment | Clerk application | instance (Development or Production) | Publishable Key prefix | Secret Key: variable, scope, key name and who confirmed it | last used, from the API keys page | IP allowlist shown | finding
A1. Local development | Kerrigan Portal | Development | pk_test_ | CLERK_SECRET_KEY present in each developer's .env.local; key name "dev-local"; confirmed by the lead developer | today | no | none
A2. Preview deployments | Kerrigan Portal | Development | pk_test_ | CLERK_SECRET_KEY, preview scope; key name "dev-local" | today | no | finding: previews share the developers' key. Clerk's rotate keys guide suggests a separate key for each place one is used, named after its consumer. A note for the next planned rotation.
A3. Staging | Kerrigan Portal Staging, a separate Clerk application | Production | pk_live_ | CLERK_SECRET_KEY, staging project; key name "staging-host" | yesterday | no | none. Clerk's environments page describes staging as a separate Clerk application with its own domain.
A4. Production | Kerrigan Portal | Production | pk_live_ | CLERK_SECRET_KEY, production scope; key name "default" | just now | no | finding: generic name, so the key list does not show where it lives
A5. CI pipeline that creates test users | Kerrigan Portal | Production | none used | CLERK_SECRET_KEY present in the CI secrets; key name "ci-seed" | 3 days ago | no | finding: a pipeline that creates test users holds a production Secret Key. The lead developer to confirm whether it should use the Development instance.
Social sign-in on the Production instance: Google, with the business's own OAuth credentials, as the lead developer confirms. Clerk's production guide says the shared credentials Clerk provides in development are not secure in production.
Decision, and who made it: ______
B. MIDDLEWARE VISIBILITY VERSUS SERVER-SIDE AUTHORISATION
Where to look: the middleware file (proxy.ts, or middleware.ts on Next.js 15 and earlier, per Clerk's clerkMiddleware() reference) and its matcher, then every page, layout, route handler and Server Action that reads or changes protected data. Clerk's guide to protecting content lists those resource types. For a Server Action, record the page that calls it.
Record per resource: resource | what it reads or changes | covered by the matcher | what middleware does with it | check inside the resource itself | query limited to the caller's user or organisation | hidden only by <Show> or a layout | combined has() or auth.protect() conditions | finding
B1. app/quotes/page.tsx | lists the organisation's quotes | yes | auth.protect() for paths matched by createRouteMatcher(['/quotes/:path*']) | none: reads orgId from auth() without checking isAuthenticated | yes, by orgId | no | no | finding: sign-in is enforced only in middleware. Clerk's reference marks createRouteMatcher() as deprecated, and GHSA-vqx2-fgx2-5wq9 (Part I) concerns apps relying only on it.
B2. app/api/quotes/[id]/route.ts, GET | returns one quote | yes | nothing: /api is not in the route matcher list | auth() and isAuthenticated | no: looks the quote up by id alone | no | no | finding: any signed-in user in any organisation could request another organisation's quote by id. A code change for the developer.
B3. app/api/quotes/[id]/route.ts, DELETE | deletes a quote | yes | nothing | has({ permission: 'org:quotes:delete' }) | yes | no | no | none
B4. Server Action approveQuote, called from /quotes | marks a quote approved | the matcher covers /quotes | auth.protect() | auth.protect({ permission: 'org:quotes:approve', reverification: 'strict' }) | yes | no | yes: a permission combined with reverification | finding: the combined shape GHSA-w24r-5266-9c3c names; compare the version in Part I.
B5. app/admin/layout.tsx and app/admin/users/page.tsx | lists every user of the portal | yes | auth.protect() | the layout checks has({ role: 'org:admin' }); the page checks nothing | n/a | layout only | no | finding: Clerk's authorisation checks guide cautions that layouts do not re-render on navigation. The page needs its own check.
B6. app/settings/billing/page.tsx | shows the billing contact's details | yes | nothing | none on the server; the details are wrapped in <Show> for admins | n/a | <Show> only | no | finding: Clerk says <Show> only hides its children visually and their contents remain in the page source.
B7. app/api/webhooks/clerk/route.ts, POST | creates and updates users in the portal's database | yes | nothing: kept public, as Clerk's syncing guide says a webhook route must be | verifyWebhook() | n/a | no | no | none (see Part H)
Decision, and who made it: ______
C. REDIRECT URLS AND DOMAINS
Where to look: the sign-in, sign-up and redirect environment variables (paths, not secrets), the props on <ClerkProvider> in the root layout, the authorizedParties option where clerkMiddleware() or authenticateRequest() is called, and the Domains page with its Allowed subdomains tab (Clerk's subdomain allowlist page).
C1. Sign-in URL /sign-in; sign-up URL /sign-up
C2. Force redirect after sign-in or sign-up: not set. Fallback redirect after sign-in and sign-up: /quotes. Clerk's environment variables page says the fallback is used if there is no redirect_url in the path already, and defaults to /.
C3. allowedRedirectOrigins and allowedRedirectProtocols on <ClerkProvider>: not set. Note for the developer: Clerk's <ClerkProvider> reference describes allowedRedirectOrigins for validating user-provided redirect URLs.
C4. authorizedParties: set in clerkMiddleware() to https://app.kerriganfreight.example on production; the staging application sets its own domain; not set locally.
C5. Enable allowed subdomains: off. Other subdomains of kerriganfreight.example and who runs each: www (the marketing site, run by an agency on another host), status (a status page service), staging (the separate staging application). Finding: Clerk's production guide strongly recommends restricting which subdomains can make cross-origin requests to the Frontend API.
C6. Satellite domains: none.
Decision, and who made it: ______
D. SESSION AND SIGN-UP SETTINGS (Production instance)
Where to look: the Sessions page (Clerk's session options page), the Access mode page (Clerk's restricting access guide), and the settings of the account lockout and user enumeration protections (Clerk's lockout and enumeration pages name the settings; this worksheet leaves their location to you).
D1. Inactivity timeout: off. Clerk's session options page says it is off by default and needs a paid plan for production use.
D2. Maximum lifetime: 7 days.
D3. Multi-session handling: off.
D4. Last change to a lifetime setting: Maximum lifetime lowered from 30 days to 7 days on 2 October 2026. Note: Clerk's session options page says a change affects only sessions created after it is saved. Whether to revoke sessions created before that date is the owner's decision.
D5. Access mode: Invite-only. Allowlist: not applicable, since Clerk's restricting access guide says it applies only in Open mode.
D6. Account lockout: Failed attempts allowed 100; Lockout duration 1 hour. Note: Clerk's lockout page says the default for new instances changed from 100 to 10 on 6 July 2026 and existing instances kept their limit. This instance was created in 2025.
D7. User enumeration Protection level: Bulk.
Decision, and who made it: ______
E. SESSION TOKEN CLAIMS YOUR SERVER READS
Where to look: the "Claims" editor under "Customize session token" on the "Sessions" page (Clerk's guide to customising session tokens), and every place your server code reads auth(), sessionClaims or has().
Record per claim: claim | default or custom | where its value comes from | where the server reads it | used for an authorisation decision | finding
E1. sub (user ID) | default | Clerk | every route, through auth().userId | yes, ownership of a user's own records | none
E2. o, the organisation claim (ID, slug, role, permissions) | default, present only while an organisation is active | Clerk | quote queries and has() | yes | none
E3. azp | default | the Origin of the browser's request to the Frontend API | checked by clerkMiddleware() against authorizedParties (C4) | yes | none
E4. sts | default | Clerk | not read | n/a | note: Kerrigan requires every user to belong to an organisation. Clerk's JWT verification guide says such a user can hold a valid token with sts set to pending until they join one. The developer to confirm how pending sessions are handled.
E5. act | default, present only during impersonation | Clerk | not read | n/a | note: the portal's activity log does not record impersonation
E6. plan (custom claim, taken from the user's unsafe metadata) | custom | unsafe metadata | the quote limit check | yes | finding: see F2
Custom claims in total: one short field, well under the 1.2KB Clerk's guide gives as the limit.
F. METADATA
Where to look: every read and write of publicMetadata, privateMetadata and unsafeMetadata in your code, and the custom claims in Part E. Clerk's user metadata guide says who can read and write each kind.
Record per key: key | kind (public, private or unsafe) | what writes it | read for an authorisation decision | copied into the session token | finding
F1. onboardingComplete | public | a Server Action after onboarding | no, routing only | yes | none
F2. plan | unsafe | the sign-up form | yes, the quote limit | yes (E6) | finding: Clerk's guide says unsafe metadata can be modified directly from the frontend and malicious users could potentially tamper with it. A code change for the developer: set the plan on the server, in public or private metadata.
F3. stripeCustomerId | private | the billing webhook handler | no | no | none
F4. internalNotes | public | the staff admin tool | no | no | finding: Clerk's guide says public metadata can be read by the frontend. Each user can therefore read the notes kept about them.
G. ORGANISATION ROLES AND PERMISSIONS
Where to look: the Roles & Permissions page (Clerk's roles and permissions guide), for which role is the creator role and which the default role. The guide gives "Set as creator role" and "Set as default role" as the menu options that reassign them, so select neither. Then the has() and auth.protect() calls in Part B.
Record per role: role key | permissions | creator or default role | who holds it | checks that use it, by role or by permission | finding
G1. org:admin | every System Permission, plus org:quotes:delete and org:quotes:approve | creator role | the first user at each customer | B5 by role; B3 and B4 by permission | none
G2. org:member | Read members, Read billing, org:quotes:read | default role | everyone invited | B2 checks sign-in only | see B2
G3. org:dispatcher (custom) | org:quotes:approve | neither | dispatch staff at two customers | B4 | note: Clerk's roles guide says custom roles in production require the B2B Authentication add-on
Note: a server-side has() check of a permission works only with Custom Permissions, because System Permissions are not in the session token claims (Clerk's authorisation checks guide).
H. WEBHOOKS
Where to look: the endpoints listed on the Webhooks page in each instance, without selecting one, because Clerk's webhooks overview says the signing secret is found by selecting the endpoint. Then the receiving route handler, the event types it acts on, and the name of the variable that holds the signing secret.
Record per endpoint: instance | receiving route (path only) | event types the handler acts on | signing-secret variable and its scope | verification in code (verifyWebhook(), a Svix library, other, none) | route kept public | repeats handled (svix-id stored, or upsert) | accepts only Svix's webhook IPs | finding
H1. Production | /api/webhooks/clerk | user.created, user.updated, user.deleted | CLERK_WEBHOOK_SIGNING_SECRET, production scope | verifyWebhook() from @clerk/nextjs/webhooks | yes | upsert for created and updated; svix-id not stored | no | note: the welcome email sent on user.created could go twice, since Clerk's overview says an event can arrive more than once
H2. Development | a tunnel address from a developer's laptop | user.created | the developer's .env.local (present: yes) | verifyWebhook() | yes | no | no | finding: the endpoint still points at a tunnel the developer confirms no longer exists. Deleting the endpoint is the owner's decision.
Decision, and who made it: ______
I. CLERK SDK VERSIONS AGAINST THE ADVISORY LOG
Where to look: the lockfile of the commit that is deployed, for every @clerk package; your code, for createRouteMatcher, combined has() or auth.protect() conditions, verifyWebhook() and frontendApiProxy; and, for GHSA-wpqf-h9rq-rg73, whether the instance issues OIDC ID tokens (an OAuth application allowed the openid scope, dynamic client registration enabled, or CIMD clients enabled), as the developer confirms. Record yes or no for each, and no client ID or client secret.
I1. Resolved versions on the deployed commit: @clerk/nextjs 6.39.1; @clerk/backend 2.33.2; @clerk/shared 3.47.3
I2. GHSA-vqx2-fgx2-5wq9 (CVE-2026-41248) | uses createRouteMatcher: yes (B1, B5) | @clerk/nextjs 6.39.1 and @clerk/shared 3.47.3 fall in the affected ranges of both records | patched: @clerk/nextjs 6.39.2 and @clerk/shared 3.47.4 on the lines in use | missing downstream checks: B1, B5
I3. GHSA-w24r-5266-9c3c (CVE-2026-42349) | combined call: yes (B4) | @clerk/nextjs 6.39.1, @clerk/backend 2.33.2 and @clerk/shared 3.47.3 fall in the affected ranges | patched: @clerk/nextjs 6.39.3, @clerk/backend 2.33.3, @clerk/shared 3.47.5
I4. GHSA-wpqf-h9rq-rg73 | @clerk/backend 2.33.2 falls in the affected range | the instance issues ID tokens: no OAuth application, dynamic client registration off, CIMD clients off | not affected, by the advisory's own condition
I5. GHSA-9mp4-77wg-rwx9 (CVE-2025-53548) | uses verifyWebhook(): yes | @clerk/nextjs 6.39.1 and @clerk/backend 2.33.2 are above the affected ranges | not affected
I6. GHSA-gjxx-92w9-8v8f (CVE-2026-34076) | uses frontendApiProxy: no | the advisory says @clerk/nextjs users are not affected | not affected
I7. GHSA-q6w5-jg5q-47vg (CVE-2024-22206) | @clerk/nextjs 6.39.1 is outside 4.7.0 to before 4.29.3 | not affected
Upgrade plan: @clerk/nextjs to 6.39.3 or later in the 6.x line, then confirm from the new lockfile that @clerk/backend and @clerk/shared resolve to the patched versions in I2 and I3, redeploy, and record the new resolved versions here. The downstream checks in B1 and B5 are needed whatever the version.
Checked against: Clerk's repository advisory page and the GitHub Advisory Database, on ______
Decision, and who made it: ______
==================================================
PART 2. BLANK WORKSHEET
Application: ______________ Framework and Clerk SDK: ______________
Production domain: ______________ Staging: ______________ Previews: ______________
Reviewed by: ______________ Date: ______________
Screens or files I could not open: ______________
A. INSTANCES, KEYS AND ENVIRONMENTS (one line per environment; names and prefixes, never values)
Environment | Clerk application | instance | Publishable Key prefix | Secret Key: variable, scope, key name, confirmed by | last used | IP allowlist shown | finding
1. ______________________________
2. ______________________________
3. ______________________________
Social sign-in providers on Production, and whose OAuth credentials each uses: ______
Decision, and who made it: ______
B. MIDDLEWARE VISIBILITY VERSUS SERVER-SIDE AUTHORISATION (one line per page, layout, route handler method or Server Action)
Resource | reads or changes | covered by matcher | middleware does | check inside the resource | query limited to caller | hidden only by <Show> or a layout | combined conditions | finding
1. ______________________________
2. ______________________________
3. ______________________________
Decision, and who made it: ______
C. REDIRECT URLS AND DOMAINS
Sign-in URL: ______ Sign-up URL: ______
Force redirects (sign-in, sign-up): ______ Fallback redirects (sign-in, sign-up): ______
allowedRedirectOrigins: ______ allowedRedirectProtocols: ______
authorizedParties, and where it is set, per environment: ______
Enable allowed subdomains: on / off Allowed subdomains: ______
Every other subdomain of the root domain, and who runs it: ______
Satellite domains: ______
Decision, and who made it: ______
D. SESSION AND SIGN-UP SETTINGS (Production instance)
Inactivity timeout: ______ Maximum lifetime: ______ Multi-session handling: ______
Last change to a lifetime setting, and its date: ______
Access mode: ______ Allowlist: ______
Account lockout, Failed attempts allowed: ______ Lockout duration: ______
User enumeration Protection level: ______
Decision, and who made it: ______
E. SESSION TOKEN CLAIMS YOUR SERVER READS (one line per claim)
Claim | default or custom | value comes from | where the server reads it | used for an authorisation decision | finding
1. ______________________________
2. ______________________________
F. METADATA (one line per key)
Key | public, private or unsafe | what writes it | read for an authorisation decision | in the session token | finding
1. ______________________________
2. ______________________________
G. ORGANISATION ROLES AND PERMISSIONS (one line per role)
Role key | permissions | creator or default role | who holds it | checks that use it | finding
1. ______________________________
2. ______________________________
H. WEBHOOKS (one line per endpoint, in each instance)
Instance | route (path only) | event types handled | signing-secret variable and scope | verification in code | route kept public | repeats handled | Svix IPs only | finding
1. ______________________________
2. ______________________________
Decision, and who made it: ______
I. CLERK SDK VERSIONS AGAINST THE ADVISORY LOG
Resolved versions on the deployed commit, for every @clerk package: ______
Uses createRouteMatcher: ______ Combined has() or auth.protect() conditions: ______
Uses verifyWebhook(): ______ Uses frontendApiProxy: ______ Instance issues OIDC ID tokens: ______
One line per advisory in the log, with affected or not and the reason: ______
Checked against Clerk's repository advisory page and the GitHub Advisory Database, on: ______
Upgrade plan, and who owns it: ______
Next review date: ______Where Clerk sits in your application
Clerk security covers the service Clerk runs and what your application does with what Clerk tells it.
Clerk's guide to how Clerk works describes a Frontend API and a Backend API. The Frontend API, which Clerk provisions for each application, handles flows for one user at a time, such as signing up, listing that user's active sessions and fetching their organisation invitations.
The Backend API handles administrative tasks that affect many users, such as listing all users, banning a user or impersonating one, and the guide says those tasks should only be executed on the server side using a secret key inaccessible to users or the browser.
At sign-in, the same guide says, Clerk creates a session record, a signed client token and a signed session token. The client token carries the session lifetime and is stored as a cookie on the Frontend API domain, where the application cannot read it.
The session token expires after 60 seconds, is set on your application's domain, and is what your server receives. Clerk's frontend SDKs refresh it on a 50-second interval. Clerk's JWT verification guide says the token reaches your backend in a cookie named `__session` or in the `Authorization` header, depending on your architecture, and that every request must be validated to ensure the token has not expired or been tampered with.
Clerk's session token reference lists what that token carries, including the user's ID and, only while an organisation is active, that organisation and the user's role in it. This guide's reading: whether that person may read or change a particular record is decided by your own code, on every route that touches it, and that decision is what this guide and its worksheet concentrate on.
The JWT security guide covers token verification in general and the session management guide covers how sessions should start and end; this guide stays with the settings and helpers Clerk provides.
What Clerk's documentation says it handles, and what it says your code must check
Clerk's documentation describes several protections built into how its sessions and sign-in work:
- Cookies and cross-site request forgery. Clerk's CSRF page says Clerk sets the SameSite flag on all of its session cookies to Lax. The same page attaches a condition for your code: because of the Lax setting, navigation alone should never trigger a change in your backend, or a user can be tricked into clicking a link that takes an action they did not intend.
- Token theft through injected script. Clerk's XSS leak protection page says Clerk uses HttpOnly cookies for authenticated requests to its Frontend API. It also says the `__session` cookie on your application's domain is not HttpOnly, because Clerk's client-side SDKs need to read it, and that the token inside has a one-minute lifetime for that reason. For maximum security, it advises against keeping session tokens in places JavaScript can read, giving as examples cookies without the HttpOnly flag, localStorage, sessionStorage and IndexedDB.
- Session fixation. Clerk's fixation page says Clerk resets the session token each time a user signs in or out of a browser, and the old token can no longer be used for authentication.
- Sign-in attacks. Clerk's lockout page says that by default new instances lock an account after 10 failed sign-in attempts, with a one-hour cooldown, that the default changed from 100 to 10 on 6 July 2026, and that existing instances kept their limit. Its user enumeration page says the Protection level setting is Bulk by default, that the protection cannot be turned off, and that under Strict a user gets no feedback on whether an account exists until they verify their identity. The broken authentication guide covers sign-in, enumeration and recovery in general.
What Clerk's guides and terms ask of the customer
The same documentation is plain about the other side. Clerk's guide to protecting content in Next.js says every resource that reads or changes protected data needs its own check. Its webhooks overview says a webhook payload should always be treated as unsafe until the incoming webhook is validated.
Clerk's Standard Terms and Conditions, last updated 1 October 2026, say under Confidentiality and Data Security that Clerk shall maintain appropriate administrative, physical and technical safeguards to protect the security of the Service and the Customer Data. The same section says that, as a condition of its right to use the Service, the customer shall establish security systems that at a minimum include mechanisms to detect and terminate unauthorised use of or access to the Service, safeguard the integrity and validity of the Credentials, and prevent unauthorised access to and protect all information stored, processed or transmitted electronically.
Your adviser can say how those duties bear on your business. For this guide they mark out the ground the worksheet covers: your routes, your keys, your webhook handler and the settings you chose.
Clerk middleware security: protect the resource, not only the route
In a Next.js application, `clerkMiddleware()` connects Clerk to each request through middleware.
Clerk's reference for it names the file `proxy.ts`, or `middleware.ts` on Next.js 15 and earlier. Clerk's webhook syncing guide says that by default `clerkMiddleware()` does not protect any routes. The reference goes further: middleware is not the best place to protect routes, and access should be protected as close to the resource as possible, in the code that reads or changes the data.
It marks `createRouteMatcher()`, the helper that lists paths for middleware to match, as deprecated, and says to migrate to resource-based auth checks.
The advisory record shows what is at stake. GHSA-vqx2-fgx2-5wq9 (CVE-2026-41248), published on Clerk's repository on 15 April 2026, says `createRouteMatcher` in `@clerk/nextjs`, `@clerk/nuxt` and `@clerk/astro` can be bypassed by certain crafted requests, allowing them to skip middleware gating and reach downstream handlers.
It says apps relying only on middleware gating through `createRouteMatcher` are affected, that auth checks inside route handlers, server components and server actions continue to work correctly, and that whether an app is affected in practice depends on whether it has those downstream checks.
Its workaround, for anyone who cannot upgrade straight away, is to add server-side `auth()` checks inside those handlers, components and actions.
Clerk's guide to protecting content lists what needs its own check in a Next.js app: Server Components (layouts and pages), Route Handlers, Server Actions, and any external API endpoint your app calls, which must enforce its own authentication.
Its authorisation checks guide adds cautions about the `<Show>` component and about layouts. The `<Show>` component only hides its children visually: their contents remain accessible in the browser's page source for a user who fails the check, and for truly sensitive data Clerk recommends `has()` on the server before the data is sent to the browser. And checks placed in layouts deserve caution, because layouts do not re-render on navigation.
Part B of the worksheet puts the two views side by side for each page, route handler and Server Action: what the middleware does with it, and what the code inside it checks. The Next.js security guide covers middleware matching, Server Actions and framework advisories in general; this section stays with Clerk's helpers.
What has() and auth.protect() return
Clerk's authorisation checks guide describes `has()` as the recommended helper: it returns false when the user is not authorised and works on the client and the server. `auth.protect()` checks that the user is both signed in and authorised, can only be used on the server, and throws a 404 error when the user is not authorised.
The same guide sets conditions on what a check can see. A server-side `has()` check of a permission works only with Custom Permissions, because System Permissions are not included in the session token claims, so a System Permission is checked through the user's role instead.
And a role or permission check depends on the user having an active organisation; without one, the guide says, the checks will likely always evaluate to false by default.
Combining conditions in one call needed a fix. GHSA-w24r-5266-9c3c (CVE-2026-42349), published on 22 April 2026, says `has()`, `auth.protect()` and related predicates can return true for certain combined authorisation checks when the result should be false. The call shapes it says can be bypassed, if certain conditions are met, combine a reverification check with a role, permission, feature or plan, or a billing check (feature or plan) with a role or permission; single-condition checks are not affected.
The same advisory records a second bypass in `@clerk/nextjs`, where `auth.protect()` silently discarded its authorisation parameters when the same argument object also held `unauthenticatedUrl`, `unauthorizedUrl` or `token`.
Its workaround, for anyone who cannot upgrade immediately, is to split combined calls into single-condition checks run one after another.
Public, private and unsafe metadata, and organisation roles
Clerk's user metadata guide describes public, private and unsafe metadata, each stored on the user.
Public metadata can be read by the frontend and the backend but set only on the backend. Private metadata can only be read and set by the backend and webhook handlers. Unsafe metadata can be read and written from both, and the guide says it is called unsafe because it can be modified directly from the frontend, which means malicious users could potentially tamper with the values. It is also the only kind that can be set during sign-up.
Clerk's own guide to basic role-based access control, written for applications that do not use Clerk's organisations, stores each user's role in public metadata, because public metadata can be read but not modified in the browser, and copies it into the session token. The metadata guide notes that a change made on the server does not appear in the session token until the next refresh.
This guide's reading: a role, plan, tenant or approval flag that decides access belongs in public or private metadata set by your server, and the worksheet flags any authorisation decision that reads unsafe metadata.
For applications that do use organisations, Clerk's roles and permissions guide describes the default roles admin (`org:admin`), with full access to the organisation's resources and every System Permission, and member (`org:member`), limited by default to the Read members and Read billing permissions. The user who creates an organisation becomes its first member with the creator role, `org:admin` by default, and new members receive the default role, `org:member` by default.
Both can be reassigned on the Roles & Permissions page, the creator role only to a role that holds the System Permissions the guide lists for it.
Custom roles are free to create in development, and in production the guide says they require the B2B Authentication add-on. Clerk's authorisation checks guide recommends permission-based over role-based checks as more granular, flexible and secure.
Clerk session settings: lifetime, inactivity and who can sign up
Clerk's session options page puts session lifetimes on the Sessions page of the Clerk Dashboard.
Web browser sessions have an Inactivity timeout and a Maximum lifetime, and at least one of them must stay enabled. Inactivity timeout is off by default, and the page says it needs a paid plan for production use.
Maximum lifetime defaults to 7 days on newly created instances, and a custom value needs a paid plan for production use. The same page says cookies set in Google Chrome have a Max-Age upper limit of 400 days.
Tightening a setting has a catch. The page says a change to a session lifetime affects only sessions created after it is saved. Existing sessions keep the lifetime they were created with, and ending them means revoking them, from the Devices section of a user on the Users page or with `revokeSession()`.
A review therefore records when each setting last changed as well as its value, and the decision to revoke older sessions stays with the owner.
Who can create an account at all is set by the access mode. Clerk's restricting access guide describes the access modes Open, Invite-only and Waitlist, chosen on the Access mode page, with Open as the default. Its allowlist applies only in Open mode, needs a paid plan for production use, and blocks all sign-ups if it is enabled with no identifiers added. Part D of the worksheet records how each of these is set on your Production instance.
Redirect URLs, subdomains and the production domain
Clerk's redirect guide says that when a user reaches a Clerk sign-in or sign-up page from a link or button, Clerk keeps the previous page's address in a `redirect_url` query string and sends the user back to it afterwards.
Force redirect URLs always send the user to the address you set and override `redirect_url`; fallback redirect URLs are used only when there is no `redirect_url`, and Clerk's environment variables page says they default to /. Clerk recommends setting these through environment variables rather than component props.
Clerk's `<ClerkProvider>` reference describes `allowedRedirectOrigins`, an array of domains to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe, the default redirect is used and a warning is logged in the console. A companion option, `allowedRedirectProtocols`, does the same for protocols. The worksheet records whether either is set. How your own routes handle a redirect parameter is outside what a settings review can show.
Domains carry a setting of their own. Clerk's production deployment guide says that by default the Frontend API accepts cross-origin requests from any subdomain of your configured root domain, which increases your application's attack surface, and strongly recommends a subdomain allowlist. Clerk's subdomain allowlist page gives the concern: if an attacker compromises one subdomain, they may be able to leverage that access to compromise authentication flows on the primary domain.
The setting is the Enable allowed subdomains toggle on the Allowed subdomains tab of the Domains page, and the primary domain is always allowed.
This guide's advice is to list every subdomain of the root domain with the business or service that runs it, including marketing sites and hosted third-party pages, before deciding which ones the allowlist needs. The subdomain takeover guide covers how a subdomain can end up in someone else's hands.
Clerk webhook verification
Clerk's webhooks overview says Clerk sends its webhooks through Svix, as an HTTP POST to the endpoint configured for each event type, and that an endpoint's signing secret is found by selecting it on the Webhooks page.
It says the payload should always be treated as unsafe until the incoming webhook is validated, because a bad actor would fake a webhook event to try to gain access to your application or data. Clerk's rotate keys guide says the signing secret, which starts with whsec_, is a shared secret between Clerk and your app, and that anyone with it can make verified requests to your webhook endpoint.
The protections the overview lists for a webhook route are verifying the request signature with Clerk's `verifyWebhook()` helper, and accepting requests only from Svix's webhook IP addresses. The `verifyWebhook()` reference says the helper verifies a request using Standard Webhooks, and recommends supplying the secret through the `CLERK_WEBHOOK_SIGNING_SECRET` environment variable.
Clerk's syncing guide adds that the webhook route must be public, because incoming webhook events carry no auth information, and that a 4xx or 5xx response, or no response code at all, means the event will be retried.
On that reading, the signature check is what guards the route, and the worksheet records it for each endpoint.
A handler also has to allow for how delivery works. The overview says delivery is at least once, so an event can arrive more than once, and that events can arrive in a different order from the one in which they occurred. Every delivery attempt for the same event carries the same svix-id header, which a handler with side effects can store to skip repeats.
Clerk's production deployment guide says webhook endpoints need to be updated to use the production instance's URL and signing secret.
Clerk's own helper has needed a fix. GHSA-9mp4-77wg-rwx9 (CVE-2025-53548), published on 9 July 2025, says applications that use `verifyWebhook()` to verify incoming Clerk webhooks are susceptible to accepting improperly signed webhook events. Its affected packages include `@clerk/backend` from 2.0.0 to before 2.4.0, patched in 2.4.0, and `@clerk/nextjs` from 6.2.10 to before 6.23.3, patched in 6.23.3.
The advisory says the issue was resolved by properly parsing the request's signatures and comparing them against the signature generated from the received event.
Test and live keys: development and production instances
Clerk's environments page says a new Clerk application comes with a Development and a Production instance, and its rotate keys guide says each app and environment combination has its own set of API keys.
Clerk's environment variables page says the Publishable Key is prefixed with pk_test_ in development instances and pk_live_ in production instances, that the Secret Key is prefixed with sk_test_ or sk_live_ in the same way, and that the Secret Key must not be exposed on the frontend with a public environment variable.
Clerk's rotate keys guide says the Publishable Key is safe to expose on the frontend, that the Secret Key must be kept private, and that rotating one instance's Secret Key does not affect the other's.
Development and Production instances are not interchangeable. Clerk's environments page says a Development instance has a more relaxed security posture and is not suitable for production workloads, is capped at 100 users, and carries session state in a querystring value that Clerk says is not secure enough for production use.
Clerk's production deployment guide says the shared OAuth credentials Clerk provides for most social providers in development are not secure in production, and that SSO connections, Integrations and Paths settings do not copy over when a production instance is cloned from development.
Clerk's troubleshooting page on using production keys in local development says production keys (pk_live_ and sk_live_) only work with the configured production domain, and calls its own method for using them locally strongly discouraged and not officially supported.
Staging and previews are where the line blurs. Clerk's environments page says a staging environment can be set up as a separate Clerk application with its own domain, which keeps live production data out of staging, and that sharing production settings and data with staging is not recommended because you would be sharing a user table.
For a preview environment on a host's own preview domain, the same page says to configure development API keys.
Secret Keys can be narrowed further. The rotate keys guide says Clerk supports multiple active Secret Keys on the same instance, suggests a separate key for each place one is used, named after its consumer, and says each key on the API keys page shows when it was last used.
Clerk's IP allowlist page says the Backend API rejects requests that use a key from IP addresses outside its allowlist, except for a listed set of requests that Clerk's SDKs make while authenticating requests, and that a key without an allowlist can be used from any IP address.
It says the feature requires the Business plan, or the plan it names alongside Business, for production use, and can be tried for free in development mode.
The `clerkMiddleware()` reference says the API keys page shows a Secret Key's full value only once, when it is added. That suits the worksheet, which records keys by name, environment and last use, never by value.
Clerk vulnerability history: advisories in Clerk's JavaScript SDKs
Clerk publishes security advisories for its JavaScript SDKs on the security page of its clerk/javascript repository on GitHub.
The entries below are the advisories that page listed when this guide read it on 14 November 2026, ordered from the 12 November 2026 entry back to the 12 January 2024 entry, each paired with its GitHub Advisory Database entry where this guide cites one.
Each gives what its record says: the packages and versions, the patched versions and the description. Where Clerk's advisory page and the database entry write a version range differently, both are given.
This log is as of 14 November 2026. Before relying on it, check Clerk's repository advisory page and the GitHub Advisory Database for each Clerk package in your lockfile, and fill in Part I of the worksheet from what you find.
Package: `@clerk/backend`, used directly or through a framework SDK. When read on 14 November 2026, the version fields of GHSA-wpqf-h9rq-rg73 listed 3.0.0 to 3.27.0 inclusive, 1.0.0 to 2.33.8 inclusive and everything below 1.0.0 as affected, and the patched versions field read None.
Check Clerk's advisory page for GHSA-wpqf-h9rq-rg73 for any later change to that field. The advisory's recommended actions name `@clerk/backend` 3.28.0 or later on the 3.x line and 2.33.9 or later on the 1.x and 2.x lines, and say the 0.x line will not receive a patch.
Description: `authenticateRequest()` and `verifyToken()` could accept an OIDC ID token as a session token, so a third-party OAuth client that a user approved could send that user's ID token to another application on the same Clerk instance and be authenticated as that user.
Only instances that issue ID tokens are affected, as set out in the section on authorised parties above. On the read date the advisory showed no known CVE.
GHSA-w24r-5266-9c3c (CVE-2026-42349) lists packages including `@clerk/nextjs` 6.0.0 to 6.39.2 and 7.0.0 to 7.2.3 inclusive, patched in 6.39.3 and 7.2.4; `@clerk/backend` 2.0.0 to 2.33.2 and 3.0.0 to 3.2.13 inclusive, patched in 2.33.3 and 3.2.14; and `@clerk/shared` 3.0.0 to 3.47.4 and 4.0.0 to 4.8.2 inclusive, patched in 3.47.5 and 4.8.3.
The advisory lists other framework packages with their own versions, and the GitHub Advisory Database gives the same `@clerk/nextjs` ranges.
Description: certain combined `has()` and `auth.protect()` calls can return true when the result should be false, and `auth.protect()` in `@clerk/nextjs` silently discarded its authorisation parameters in the case described in the middleware section above.
Packages named in GHSA-vqx2-fgx2-5wq9 (CVE-2026-41248): `@clerk/nextjs`, `@clerk/nuxt`, `@clerk/astro` and `@clerk/shared`. For `@clerk/nextjs`, the GitHub Advisory Database lists 5.0.0 to before 5.7.6, 6.0.0-snapshot.vb87a27f to before 6.39.2, and 7.0.0 to before 7.2.1 as affected, patched in 5.7.6, 6.39.2 and 7.2.1. Clerk's own advisory page gives the same patched versions and writes the affected range as 5.0.0 to 6.39.1 and 7.0.0 to 7.2.0 inclusive.
For `@clerk/shared`, the database lists 2.20.17 to before 2.22.1, 3.0.0-canary.v20250225091530 to before 3.47.4, and 4.0.0 to before 4.8.1, patched in 2.22.1, 3.47.4 and 4.8.1, and Clerk's own advisory page gives the same patched versions and writes the affected range as 2.20.17 to 3.47.3 and 4.0.0 to 4.8.0 inclusive.
Both records list `@clerk/nuxt` and `@clerk/astro` with their own ranges. Description: `createRouteMatcher` can be bypassed by certain crafted requests that skip middleware gating and reach downstream handlers. The advisory says sessions are not compromised and no existing user can be impersonated.
GHSA-gjxx-92w9-8v8f (CVE-2026-34076) lists `@clerk/backend` 3.0.0 to 3.2.2 inclusive, fixed in 3.2.3, with `@clerk/express`, `@clerk/hono` and `@clerk/fastify` listed with their own ranges. Description: the `clerkFrontendApiProxy` function is vulnerable to server-side request forgery, and an unauthenticated attacker can craft a request path that causes the proxy to send the application's Clerk Secret Key to an attacker-controlled server.
Only applications that opted into the `frontendApiProxy` feature are affected, the feature is not enabled by default, and the advisory says users of `@clerk/nextjs` are not affected because of how the framework handles a repeated / in request paths. For an application on an affected version that uses the built-in proxy, its recommended actions are to upgrade, rotate the Clerk Secret Key after upgrading, and audit access logs for requests to the proxy endpoint containing double slashes. Rotating a key changes the system, and is a decision for whoever owns it.
GHSA-9mp4-77wg-rwx9 (CVE-2025-53548) lists packages including `@clerk/backend` 2.0.0 to before 2.4.0, patched in 2.4.0, and `@clerk/nextjs` 6.2.10 to before 6.23.3, patched in 6.23.3; the advisory lists other framework packages with their own versions. Description: applications that use the `verifyWebhook()` helper to verify incoming Clerk webhooks are susceptible to accepting improperly signed webhook events.
The advisory's workaround for anyone unable to upgrade is to verify webhook signatures without the helper, following Clerk's documentation.
GHSA-q6w5-jg5q-47vg (CVE-2024-22206) lists `@clerk/nextjs` 4.7.0 to before 4.29.3, fixed in 4.29.3, and says only the `@clerk/nextjs` SDK is impacted. Description: unauthorised access or privilege escalation due to a logic flaw in `auth()` in the App Router or `getAuth()` in the Pages Router, for applications that use those calls in a Next.js backend to authenticate API Routes, App Router or Route handlers.
How to fill in the Clerk integration worksheet
Fill in one worksheet per application and work through it in order: keys first, because they decide which instance everything else belongs to, then routes, redirects and domains, sessions, claims, metadata, roles, webhooks and, last, the SDK versions.
Part 1 is a worked example for an invented freight quoting portal. Part 2 is the blank form.
- Every part is a reading: of the Clerk Dashboard, of your hosting provider's list of environment variables by name and scope, where the only values read are the Publishable Key's prefix and the sign-in and redirect paths, which are not secrets, of your own code and lockfile, and of your own pages in an ordinary browser visit. No step changes a setting, rotates or reveals a key, signs in as one of your users, or sends test requests to Clerk's services or to any other system.
- Names, never values. Record a Secret Key by its name on the API keys page, the environment it is set in and its last-used time. Record a Publishable Key by its prefix alone. Record a webhook signing secret by the name of the variable that holds it, and read the Webhooks page's list of endpoints without opening one. Where a file such as an .env file can hold a key, record only whether the variable name is there, found with a search that does not display the file.
- Do not decode or paste a real user's session token. The claims in Part E come from your code and the Clerk Dashboard.
- A screen or tab is named only where a Clerk page cited on this guide names it, and that page is given beside it. Other rows say what to read and leave finding it to you.
- Clerk's securing your app page describes a `clerk security` command that audits an instance against Clerk's security recommendations, and a `clerk security fix` command that applies supported fixes. Applying fixes changes the instance, so the worksheet runs neither command; whether to use them is the owner's decision.
- Date the worksheet, and redo it after an SDK upgrade, a new route or Server Action, a new webhook, a change of plan, or someone with Clerk Dashboard access leaving. Clerk's pages were read for this guide on 14 November 2026.
What a review of your own Clerk setup cannot show
The worksheet records settings, code paths and versions.
It cannot show the following:
- Clerk's own systems: its infrastructure, staff access and audits. For those you have what Clerk publishes and, under its Standard Terms, a copy of its then-current SOC 2 audit report or other similar independent third-party annual audit report, which Clerk shall provide on the customer's request.
- Whether your routes refuse a request the interface never sends. Reading code shows the check that is meant to run; a request from a second account, or with no session, is what shows the running build's answer.
- Whether a Secret Key or signing secret has already been copied somewhere it should not be. The worksheet shows where each one is meant to be.
- Timing, such as the minute in which a session token can still carry a role or plan that has just changed.
- What a third-party OAuth client that a user approved can do with that user's tokens, beyond the advisory conditions recorded in Part I.
- Advisories published after the review date, and settings changed after it.
Clerk's vulnerability disclosure policy
Clerk's vulnerability disclosure policy sets out how researchers report security issues in Clerk's own products.
It requires that all researchers make every effort to avoid privacy violations, degradation of user experience, disruption to production systems and destruction of data during security testing, research only within the scope it sets out, report through the channels it identifies, and keep vulnerability information confidential until Clerk has had 90 days to resolve the issue.
Its scope lists dashboard.clerk.com, accounts.clerk.com, api.clerk.com, clerk.clerk.com and production instances created on dashboard.clerk.com. Its exclusions include findings in Development or Staging instances, findings from physical testing, findings derived primarily from social engineering, findings from systems not listed in the scope, and network-level denial-of-service vulnerabilities.
This guide reads the policy as written for researchers reporting a vulnerability in Clerk's services, and does not read it as permission for any particular test of your own application. Before anything active is pointed at a sign-in flow, webhook or API that Clerk runs, read Clerk's terms and the policy as they stand on the day, ask Clerk in writing, and record the answer with its date. The worksheet itself sends no test requests to Clerk.
Where Clever Ops fits around a Clerk integration
Clever Ops offers no service for Clerk itself and does not test Clerk's platform.
Under the Clever Ops methodology, a service another business runs is outside the method and stays out of scope unless that business agrees.
Testing your own application while it runs, from its pages and route handlers to its Server Actions and webhook handler, belongs in a scoped web application and API penetration test. That test signs in with accounts in each role in scope and looks at authentication and sessions, at what each role can see and change, at whether one customer can reach records that belong to another, and at the API when it is called directly rather than through the screens.
Its scope asks for two accounts per role, plus accounts in two separate customer organisations where your app serves more than one.
A secure code review works from the source instead: it lists each way into the code in scope, such as route handlers, Server Actions and webhooks, and follows each one from the request to the query.
When the application is one Clever Ops built or hosts, the work is reported as a security review instead of an independent test, and the report records who built the application and who hosts it.
Round-the-clock monitoring and emergency incident response are services Clever Ops does not sell. Where a Clerk key or a user account may be under misuse now, Clerk and an incident response specialist come first, ahead of any review or test.
Frequently asked questions
This guide gives no verdict on any vendor. Clerk's documentation describes its own measures, among them session cookies set to SameSite Lax, HttpOnly cookies for requests to its Frontend API, a session token that expires after 60 seconds, and a session token reset each time a user signs in or out. Its Standard Terms say Clerk shall maintain appropriate administrative, physical and technical safeguards and provide its SOC 2 audit report, or a similar independent annual audit report, on request. The same terms put duties on the customer, and Clerk's guide to protecting content says every resource that reads or changes protected data needs its own check. Those checks live in your application's code.
No. Clerk's webhook syncing guide says that by default `clerkMiddleware()` does not protect any routes. Clerk's reference for it says middleware is not the best place to protect routes and that access should be protected as close to the resource as possible, and it marks `createRouteMatcher()` as deprecated. GHSA-vqx2-fgx2-5wq9 (CVE-2026-41248) says certain crafted requests can bypass `createRouteMatcher` gating, and that auth checks inside route handlers, server components and server actions continue to work correctly.
Clerk's rotate keys guide says the Publishable Key is safe to expose on the frontend and does not need rotating if it is committed to a repository or otherwise made public. It is prefixed with pk_test_ in a development instance and pk_live_ in production. The Secret Key is different: the same guide says it must be kept private, and Clerk's environment variables page says not to expose it on the frontend with a public environment variable.
Clerk's webhooks overview says the payload should be treated as unsafe until the webhook is validated, and lists verifying the signature with `verifyWebhook()` and accepting requests only from Svix's webhook IPs. Clerk's environment variables page says the helper reads the signing secret from `CLERK_WEBHOOK_SIGNING_SECRET`. GHSA-9mp4-77wg-rwx9 (CVE-2025-53548) says applications using `verifyWebhook()` were susceptible to accepting improperly signed events on `@clerk/backend` 2.0.0 to before 2.4.0 and `@clerk/nextjs` 6.2.10 to before 6.23.3, among other packages. Compare the resolved versions in your lockfile with those ranges.
Clerk's environments page says a Development instance has a more relaxed security posture and is not suitable for production workloads. It is capped at 100 users, uses shared credentials for some social connections by default, and carries session state in a querystring value that Clerk says is not secure enough for production use. The same page says a production domain must be associated with a Production instance, and Clerk's environment variables page says production keys are prefixed with pk_live_ and sk_live_.
In Clerk's metadata guide, unsafe metadata is the kind of user metadata that the frontend can both read and write. The guide says it is called unsafe because it can be modified directly from the frontend, which means malicious users could potentially tamper with the values, and that it is the only metadata that can be set during sign-up. By the same guide, public metadata can be read by the frontend but set only on the backend, and private metadata can only be read and set by the backend and webhook handlers. This guide's advice is to base no authorisation decision on unsafe metadata.
Scope the right test for your application
Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.