Clerk in production: the choices its own skills cannot make
Decide the product's access model before following Clerk's API guidance. Clerk's own agent skills know the API. They cannot decide:
- where a session is verified, and what may read it;
- what a workspace is;
- where billing ends and authorization begins;
- which dashboard settings silently change what your code is allowed to do.
Those decisions are here.
Where Clerk's defaults or quickstarts contradict this skill, this skill wins. These mechanics use Next.js App Router, Next 16 (proxy.ts middleware), Clerk Core 3 (@clerk/nextjs v7), Supabase and Netlify. Apply saas-authorization for the access model, which carries to any identity provider.
Use the product's integration notes, permission module and member home. Integration notes hold dated provider configuration: instances, settings, slugs and read-backs. The permission module maps roles to permission strings. The member home is the sign-in destination, /dashboard unless the product names another.
Clerk's own skills: get them, prefer them for the API
- Use Clerk's own skills for its API. The set comes from the GitHub repository
clerk/skills:
clerk (a router);
clerk-setup, clerk-nextjs-patterns, clerk-custom-ui, clerk-orgs, clerk-billing, clerk-webhooks, clerk-testing;
clerk-backend-api (browse and call the Backend API);
clerk-cli.
- Install and vendor the skills instead of relying on API memory. Run
npx skills add clerk/skills with the open skills CLI. Vendor them into the product's skills folder so they load whenever Clerk is touched, and prefer them over training-era memory of the API.
- Pin the skills and update them deliberately. A
skills-lock.json records each skill's source, its path and a content hash. npx skills update refreshes them on purpose.
- Refuse vendor suggestions that contradict this skill. These include:
createRouteMatcher path lists;
<SignedIn> and <SignedOut>, which Core 3 deleted;
<ClerkProvider dynamic>;
- rebuilt sign-in screens;
clerk.signIn() in the browser suite;
- Clerk permissions with features attached;
- a hand-written CSP.
The choices
- Verify, never decode, always behind one session seam. Use
SessionVerifier. Tests substitute a mock verifier when CLERK_SECRET_KEY is absent; keyless mode is for development only. → references/sessions-and-front-door.md § Sessions
- Store Clerk ids only. Read names and emails from Clerk at render time. Only the
workspaces table holds a Clerk org or user id, and, where the product records authorship, one member table beside it holds the user id too (saas-authorization).
- Authorization lives with the data, not in a path list. Clerk v7 deprecates
createRouteMatcher, and proxy.ts only attaches the session. Every protected page and every action checks for itself; a check in a layout alone is not a check.
- Clerk's own components are the sign-in surface. Use
<SignIn />, <SignUp />, <UserButton />. They are dressed through appearance, never rebuilt.
- Sign-in lands on the member home, never on
/.
signInFallbackRedirectUrl and signUpFallbackRedirectUrl name the member home, and afterSignOutUrl is /.
- The member home sends a signed-out visitor to
/sign-in with a redirect_url back to itself.
- The root
<ClerkProvider> takes nonce, never dynamic: the root layout reads it from the request's content-security-policy header, the 'nonce-…' in script-src (references/sessions-and-front-door.md).
- The front door reads no session.
/ and every public page never call auth(), the seam or <Show>, and a signed-in visitor is never redirected away. The header's one button is labelled from the __client_uat cookie. → references/sessions-and-front-door.md § The front door and the member home
- In the organization shape, Membership required goes on at setup, before the first migration. The authenticated harness then creates each test account's organization. In the individual shape, organizations stay off. →
references/organizations-and-billing.md § Organizations
- Organization management is Clerk's own modal. Never build a separate page. What it lacks goes in as a custom page inside it, whose Server Actions re-resolve the caller and recheck the permission.
- With Clerk Billing, plans and features live in a file the Clerk CLI applies, and a test reads each instance back against it. The gated features are hidden from the pricing table and ride the session token, where
has() reads them; one plan module maps them to capacities. A caller with no session that the server handles (an API token, a job) reads the subscription for the plan id and takes that plan's slugs from the plan list, never from the subscription's embedded plan.features; an anonymous visitor's action uses the allowance stamped on its resource (saas-authorization). Checkout is <PricingTable for="organization">, and no price is typed into application code. → references/organizations-and-billing.md § Billing
- Never attach a feature to a Clerk permission. With billing enabled, Clerk gates permissions by feature, so a lapsed subscription silently removes a capability rather than a quota: a member loses permission to act in the middle of a session. Roles decide who may act, features decide how much, and they meet nowhere.
- The CSP comes from Clerk's middleware, never a hand-written policy. →
references/csp-and-variables.md § The CSP header
- Clerk's wording is not part of your contract. Locate its controls by their element-key class (
.cl-<elementKey>), never by their text.
- Read the gotchas before touching Clerk. Read
references/gotchas.md, since these can fail silently or look like a different problem:
- a task that runs before the app;
- Test mode as a dashboard toggle;
- a development instance's silent
dev-browser-missing refusal;
- wording that is not in your tree;
- the components Core 3 deleted;
- the provider's
dynamic and the server redirect that ignores signInUrl;
- middleware that makes a page wait;
- the bounce lost when members move off
/;
- a secret key in the publishable variable;
- a provider-less surface linking into one that needs Clerk;
- Clerk's menus opening behind a modal dialog, and a design token that loops through Clerk's own variable;
- the plan tab that must match the workspace model;
- the organization profile's navigation, hidden rather than unmounted below its breakpoint;
- a dashboard feature's slug derived from its name, and a billing patch that moves features to Free;
- a subscription read that carries only a plan's visible features;
- the personal-data webhooks, and Clerk's own deletion paths;
- production keys that refuse any host not on the instance's domain list, such as the host's default deploy subdomain, which still serves pages;
- sign-in down while every page answers 200;
- the production instance's DNS and legal consent.
Setting it up, in order
Apply every setup step on the development instance first.
- Create the application. The dashboard offers a long "Add authentication" prompt: don't paste it. In a repository it does not recognise, it scaffolds an app of its own in a subfolder (observed 2026-08). The page you want is Configure → API keys. Choose the sign-in methods: email, and Google if you want one-click sign-in.
- Set the workspace model before the first migration and billing.
- In the organization shape, turn Organizations on and set Membership required (the switch Clerk calls Force organization selection). Do it now, before the first migration and before billing.
- In the individual shape, leave Organizations off.
- Turn off Clerk's own deletion paths. Keep them off until the product can delete what a workspace owns. This covers an admin deleting an organization and a user deleting their own account. →
references/organizations-and-billing.md § Webhooks and personal data
- Configure a second role only when the organization-shaped product has one.
- In Configure → Organizations → Roles, edit the default Member role and rename it, name and key, to the product's second role (for example
org:moderator). A product whose second role is a plain member keeps org:member.
- Leave Admin (
org:admin) alone: Clerk gives it to whoever creates an organization, and an instance cannot be without it.
- Define no Clerk permissions.
- Enable Test mode before running the authenticated browser suite. Use Configure → Instance → Test mode: on.
- Change the default verification code: it is the password to every test account on the instance.
- Create one user with a
+clerk_test address by hand, the fastest proof that Test mode is really on. → references/authenticated-mile.md
The agent can make three setup changes through the Backend API. For steps 2–4, it can use development's secret key and get read-backs the dashboard does not give. Clerk's Backend API spec was read 2026-11-02 (spec of 2026-08-20):
- the admin's deletion path:
PATCH /v1/instance/organization_settings with admin_delete_enabled: false, read back with GET on the same path;
- the second role:
PATCH /v1/organization_roles/{id} with its new name and key (the key starts with org:, and a new key carries over to the organization settings where the role is the creator's or the default), read back with GET /v1/organization_roles;
- test mode:
PATCH /v1/instance with test_mode: true. No GET returns it, so the +clerk_test user above is its proof.
The rest stays the owner's, in the dashboard.
Configure billing only when the product bills, after organizations. Use Free and one paid plan for organizations, written in a billing file (its plans block included) and applied in two commands: npx clerk config patch --file <file> --dry-run, read what it would send, then the same without --dry-run. Manage billing goes to the admin role alone. → references/organizations-and-billing.md § Billing
Enable legal consent once the legal pages are live. Use Configure → Legal → Require express consent to legal documents, with their URLs. The sign-up form then carries the consent checkbox.
Configure OAuth application settings only for an MCP server. See § MCP OAuth.
Configure production's own instance at go-live. It gets:
- its own keys, which work only on the domains the instance is configured for, and its DNS records;
- its own OAuth client for each social sign-in (development borrows Clerk's shared ones);
- legal consent on;
- a real Stripe account connected to Clerk Billing, and the billing file applied with the same two commands plus
--instance prod, the dry run read first, when the product bills;
- every dashboard setting above applied again and read back. An instance cloned from development drops the settings only the API sets (observed
2026-10-24);
- generated secrets generated afresh, never copied from development.
→ references/csp-and-variables.md § The production instance; the release around it is release-gate.
Keep a record of every dashboard setting
Record dated read-backs for settings and screenshots only where unreadable. None lives in application code, and several silently change what that code may do. Put each in the integration notes:
- the plans and features: the billing file, and each instance's read-back against it (§ The choices, 9);
- the organization settings,
GET /v1/instance/organization_settings with that instance's secret key: Membership required, automatic first organization, admin deletion off;
- the OAuth settings,
GET /v1/instance/oauth_application_settings (§ MCP OAuth);
- sign-in methods, legal consent, self-deletion and social providers, from the instance's public settings,
GET https://<frontend API host>/v1/environment, which needs no key;
- a screenshot for the rest: Roles (each role's name and key, and who holds Manage billing), Test mode on (development only), Webhooks (the endpoint and its events, once the personal-data trigger fires).
npx clerk config pull --instance <dev|prod> prints an instance's configuration as JSON as well (Clerk CLI 4.0.0, read 2026-10-25). A screenshot records intended configuration, not the live value. Read the live value back before relying on it.
MCP OAuth
Apply these OAuth settings only for a member-authenticated MCP server. Outside agents must reach it as signed-in members, with Clerk as authorization server. This section holds only Clerk settings. Apply mcp-server for callers, the route, limits, tools, directories, clients and package. That skill also covers agent-started sign-up through Create first organization automatically, an organization setting rather than an OAuth one.
Use OAuth applications → Settings (observed 2026-10-06); these settings can fail silently.
- Create no OAuth application by hand. MCP clients register themselves (DCR) or identify by a metadata URL (CIMD). Clerk says a DCR client appears under OAuth applications → Applications after its first sign-in. A CIMD client may not appear at all (Backend API observed
2026-10-27; the dashboard was not checked). A manual application is only for a client that can do neither. It needs the consent screen on and the same scopes, because instance defaults do not rewrite its scopes.
- Enable CIMD support and admit any compatible CIMD client. Set Client admission to Any compatible CIMD client. That is
client_id_metadata_documents_advertised true, with client_id_metadata_documents_only_allow_pre_registered_clients and client_id_metadata_documents_block_implicitly_allowed_clients both false. When the switch goes on, the dashboard preselects pre-registered and previously connected clients, which refuses every new client.
- Enable published DCR support even though Clerk labels it deprecated. Set
dynamic_oauth_client_registration on; Clerk labels it Deprecated. Many MCP clients still register only through DCR.
- Set default scopes for identity and, where applicable, organizations. Use
openid, profile, email, plus user:org:read in the organization shape.
- Without
user:org:read, the consent screen asks for no organization, and every connection is refused organization_required.
- The dashboard shows
offline_access and will not remove it. It is not stored in default_scopes, and it only lets a client that asks for it refresh. ChatGPT asks for it (observed 2026-10-27).
- Require PKCE. Turn
pkce_required on.
- Enable JWT access tokens and include the audience. Turn on
oauth_jwt_access_tokens and Include Audience (aud_claim_enabled, off by default).
- The route requires its own exact URL as the resource in
aud: <APP_URL>/api/mcp by default, or the path the product chose instead (one product mounts it at /mcp).
- The protected-resource metadata describes that path, never the origin root.
- Apply, then re-read. Use
PATCH, then GET /v1/instance/oauth_application_settings, with that instance's own secret key. Record the re-read in the integration notes: development and production separately, dated.
- An instance cloned from development does not carry these settings. (Observed
2026-10-24.) Apply and re-read them on the clone as on any new instance.
- No new environment variable. The publishable key gives the issuer, the secret key verifies tokens and reads membership, and
APP_URL gives the resource and the discovery URLs.
Allow for all four OAuth verification behaviours in the route.
- Discovery's
claims_supported is not the shape of the JWT Clerk emits. The list omits client_id and scope, which a real grant can carry. Run a real DCR + PKCE grant before changing which claims the route requires.
- A JWKS or network failure while verifying is a retryable
503, never an invalid-token 401. A 401 sends the client back through the whole OAuth flow.
- An unknown
kid never reaches Clerk's verifier. Given a kid it has not cached, verifyToken fetches the JWKS from the Backend API with the secret key, and an unauthenticated caller chooses the kid. Check the unverified header's kid against the key list last loaded, refresh that list at most once a minute, and refuse the rest as invalid.
- Offline JWT verification does not see a revoked grant until the token expires. It remains unseen until token expiry, a day by default. Recheck workspace access on every request through
requireWorkspaceAccess, never from the token's claims alone.
Each rule's origin, the case that taught it, is in receipts.md beside this file; read it when a rule's edge is unclear.
How you can tell it worked
A new user signs up on a phone against production and lands where they should, in the right organization and role. The served pages carry the production publishable key.
Files
| File |
Holds |
Read when |
references/sessions-and-front-door.md |
the session seam; ids only; the sign-in surface and redirects; the front door and the member home: the rule, its shape on this stack, what was rejected, the tests that pin it |
adding sign-in; touching the root layout, a public page, the member home or a redirect |
references/organizations-and-billing.md |
organizations and the choose-organization task; roles and Manage billing; the organization modal and custom pages; Clerk Billing: the billing file and the CLI, in code (callers with no session included) and in tests; pricing; webhooks, personal data and Clerk's own deletion paths |
adding organizations, a role, a plan, a limit, pricing or a deletion webhook |
references/csp-and-variables.md |
the nonce CSP and static headers; every Clerk variable and the env schema's Clerk checks; what to record; the production instance |
adding a CSP or a third-party origin; adding or checking a Clerk key; going live |
references/authenticated-mile.md |
Clerk's half of a real-session browser suite: Test mode, test accounts, the testing token, organizations in globalSetup, signing in through <SignIn />, the signed-out-action trap, locators |
writing or debugging an authenticated end-to-end test |
references/gotchas.md |
every Clerk gotcha, each with its symptom and receipt |
before touching Clerk; when sign-in or an authenticated action seems to do nothing |
When something is learned
- Keep general Clerk lessons here with their receipts. Include the date, what happened, the product named by kind.
- Date what Clerk did or required. Use "observed 2026-10", because the dashboard and its labels change without notice. When one changes, correct the line; never leave the old one beside the new.
- Keep product-specific facts in its own integration notes. This includes its instances, roles, slugs, confirmations and re-reads.
1---2name: clerk-production3description: "Setting up or changing Clerk sign-in, organizations, roles or billing on Next.js, or sign-in that does nothing or lands wrong: Clerk in production."4metadata:5 source: https://skillmd.com/skills/phuryn/clerk-production6---78# Clerk in production: the choices its own skills cannot make910**Decide the product's access model before following Clerk's API guidance.** Clerk's own agent skills know the API. They cannot decide:1112- where a session is verified, and what may read it;13- what a workspace is;14- where billing ends and authorization begins;15- which dashboard settings silently change what your code is allowed to do.1617Those decisions are here.1819**Where Clerk's defaults or quickstarts contradict this skill, this skill wins.** These mechanics use Next.js App Router, Next 16 (`proxy.ts` middleware), Clerk Core 3 (`@clerk/nextjs` v7), Supabase and Netlify. Apply `saas-authorization` for the access model, which carries to any identity provider.2021**Use the product's integration notes, permission module and member home.** Integration notes hold dated provider configuration: instances, settings, slugs and read-backs. The permission module maps roles to permission strings. The member home is the sign-in destination, `/dashboard` unless the product names another.2223## Clerk's own skills: get them, prefer them for the API2425- **Use Clerk's own skills for its API.** The set comes from the GitHub repository `clerk/skills`:26 - `clerk` (a router);27 - `clerk-setup`, `clerk-nextjs-patterns`, `clerk-custom-ui`, `clerk-orgs`, `clerk-billing`, `clerk-webhooks`, `clerk-testing`;28 - `clerk-backend-api` (browse and call the Backend API);29 - `clerk-cli`.30- **Install and vendor the skills instead of relying on API memory.** Run `npx skills add clerk/skills` with the open `skills` CLI. Vendor them into the product's skills folder so they load whenever Clerk is touched, and prefer them over training-era memory of the API.31- **Pin the skills and update them deliberately.** A `skills-lock.json` records each skill's source, its path and a content hash. `npx skills update` refreshes them on purpose.32- **Refuse vendor suggestions that contradict this skill.** These include:33 - `createRouteMatcher` path lists;34 - `<SignedIn>` and `<SignedOut>`, which Core 3 deleted;35 - `<ClerkProvider dynamic>`;36 - rebuilt sign-in screens;37 - `clerk.signIn()` in the browser suite;38 - Clerk permissions with features attached;39 - a hand-written CSP.4041## The choices42431. **Verify, never decode, always behind one session seam.** Use `SessionVerifier`. Tests substitute a mock verifier when `CLERK_SECRET_KEY` is absent; keyless mode is for development only. → `references/sessions-and-front-door.md § Sessions`442. **Store Clerk ids only.** Read names and emails from Clerk at render time. Only the `workspaces` table holds a Clerk org or user id, and, where the product records authorship, one member table beside it holds the user id too (`saas-authorization`).453. **Authorization lives with the data, not in a path list.** Clerk v7 deprecates `createRouteMatcher`, and `proxy.ts` only attaches the session. Every protected page and every action checks for itself; a check in a layout alone is not a check.464. **Clerk's own components are the sign-in surface.** Use `<SignIn />`, `<SignUp />`, `<UserButton />`. They are dressed through `appearance`, never rebuilt.475. **Sign-in lands on the member home, never on `/`.**48 - `signInFallbackRedirectUrl` and `signUpFallbackRedirectUrl` name the member home, and `afterSignOutUrl` is `/`.49 - The member home sends a signed-out visitor to `/sign-in` with a `redirect_url` back to itself.50 - The root `<ClerkProvider>` takes `nonce`, never `dynamic`: the root layout reads it from the request's `content-security-policy` header, the `'nonce-…'` in `script-src` (`references/sessions-and-front-door.md`).516. **The front door reads no session.** `/` and every public page never call `auth()`, the seam or `<Show>`, and a signed-in visitor is never redirected away. The header's one button is labelled from the `__client_uat` cookie. → `references/sessions-and-front-door.md § The front door and the member home`527. **In the organization shape, *Membership required* goes on at setup, before the first migration.** The authenticated harness then creates each test account's organization. In the individual shape, organizations stay off. → `references/organizations-and-billing.md § Organizations`538. **Organization management is Clerk's own modal.** Never build a separate page. What it lacks goes in as a custom page inside it, whose Server Actions re-resolve the caller and recheck the permission.549. **With Clerk Billing, plans and features live in a file the Clerk CLI applies, and a test reads each instance back against it.** The gated features are hidden from the pricing table and ride the session token, where `has()` reads them; one plan module maps them to capacities. A caller with no session that the server handles (an API token, a job) reads the subscription for the plan id and takes that plan's slugs from the plan list, never from the subscription's embedded `plan.features`; an anonymous visitor's action uses the allowance stamped on its resource (`saas-authorization`). Checkout is `<PricingTable for="organization">`, and no price is typed into application code. → `references/organizations-and-billing.md § Billing`5510. **Never attach a feature to a Clerk permission.** With billing enabled, Clerk gates permissions by feature, so a lapsed subscription silently removes a *capability* rather than a quota: a member loses permission to act in the middle of a session. Roles decide who may act, features decide how much, and they meet nowhere.5611. **The CSP comes from Clerk's middleware, never a hand-written policy.** → `references/csp-and-variables.md § The CSP header`5712. **Clerk's wording is not part of your contract.** Locate its controls by their element-key class (`.cl-<elementKey>`), never by their text.5813. **Read the gotchas before touching Clerk.** Read `references/gotchas.md`, since these can fail silently or look like a different problem:59 - a task that runs before the app;60 - Test mode as a dashboard toggle;61 - a development instance's silent `dev-browser-missing` refusal;62 - wording that is not in your tree;63 - the components Core 3 deleted;64 - the provider's `dynamic` and the server redirect that ignores `signInUrl`;65 - middleware that makes a page wait;66 - the bounce lost when members move off `/`;67 - a secret key in the publishable variable;68 - a provider-less surface linking into one that needs Clerk;69 - Clerk's menus opening behind a modal dialog, and a design token that loops through Clerk's own variable;70 - the plan tab that must match the workspace model;71 - the organization profile's navigation, hidden rather than unmounted below its breakpoint;72 - a dashboard feature's slug derived from its name, and a billing patch that moves features to Free;73 - a subscription read that carries only a plan's visible features;74 - the personal-data webhooks, and Clerk's own deletion paths;75 - production keys that refuse any host not on the instance's domain list, such as the host's default deploy subdomain, which still serves pages;76 - sign-in down while every page answers 200;77 - the production instance's DNS and legal consent.7879## Setting it up, in order8081**Apply every setup step on the development instance first.**82831. **Create the application.** The dashboard offers a long "Add authentication" prompt: don't paste it. In a repository it does not recognise, it scaffolds an app of its own in a subfolder (observed 2026-08). The page you want is *Configure → API keys*. Choose the sign-in methods: email, and Google if you want one-click sign-in.842. **Set the workspace model before the first migration and billing.**85 - In the organization shape, turn *Organizations* on and set *Membership required* (the switch Clerk calls *Force organization selection*). Do it now, before the first migration and before billing.86 - In the individual shape, leave *Organizations* off.87 - **Turn off Clerk's own deletion paths.** Keep them off until the product can delete what a workspace owns. This covers an admin deleting an organization and a user deleting their own account. → `references/organizations-and-billing.md § Webhooks and personal data`883. **Configure a second role only when the organization-shaped product has one.**89 - In *Configure → Organizations → Roles*, edit the default Member role and rename it, name and key, to the product's second role (for example `org:moderator`). A product whose second role is a plain member keeps `org:member`.90 - Leave Admin (`org:admin`) alone: Clerk gives it to whoever creates an organization, and an instance cannot be without it.91 - Define no Clerk permissions.924. **Enable Test mode before running the authenticated browser suite.** Use *Configure → Instance → Test mode*: on.93 - Change the default verification code: it is the password to every test account on the instance.94 - Create one user with a `+clerk_test` address by hand, the fastest proof that Test mode is really on. → `references/authenticated-mile.md`9596**The agent can make three setup changes through the Backend API.** For steps 2–4, it can use development's secret key and get read-backs the dashboard does not give. Clerk's Backend API spec was read `2026-11-02` (spec of `2026-08-20`):9798- the admin's deletion path: `PATCH /v1/instance/organization_settings` with `admin_delete_enabled: false`, read back with `GET` on the same path;99- the second role: `PATCH /v1/organization_roles/{id}` with its new `name` and `key` (the key starts with `org:`, and a new key carries over to the organization settings where the role is the creator's or the default), read back with `GET /v1/organization_roles`;100- test mode: `PATCH /v1/instance` with `test_mode: true`. No `GET` returns it, so the `+clerk_test` user above is its proof.101102The rest stays the owner's, in the dashboard.1031045. **Configure billing only when the product bills, after organizations.** Use Free and one paid plan for organizations, written in a billing file (its `plans` block included) and applied in two commands: `npx clerk config patch --file <file> --dry-run`, read what it would send, then the same without `--dry-run`. *Manage billing* goes to the admin role alone. → `references/organizations-and-billing.md § Billing`1056. **Enable legal consent once the legal pages are live.** Use *Configure → Legal → Require express consent to legal documents*, with their URLs. The sign-up form then carries the consent checkbox.1067. **Configure OAuth application settings only for an MCP server.** See § MCP OAuth.1078. **Configure production's own instance at go-live.** It gets:108 - its own keys, which work only on the domains the instance is configured for, and its DNS records;109 - its own OAuth client for each social sign-in (development borrows Clerk's shared ones);110 - legal consent on;111 - a real Stripe account connected to Clerk Billing, and the billing file applied with the same two commands plus `--instance prod`, the dry run read first, when the product bills;112 - every dashboard setting above applied again and read back. An instance cloned from development drops the settings only the API sets (observed `2026-10-24`);113 - generated secrets generated afresh, never copied from development.114115 → `references/csp-and-variables.md § The production instance`; the release around it is `release-gate`.116117## Keep a record of every dashboard setting118119**Record dated read-backs for settings and screenshots only where unreadable.** None lives in application code, and several silently change what that code may do. Put each in the integration notes:120121- the plans and features: the billing file, and each instance's read-back against it (§ The choices, 9);122- the organization settings, `GET /v1/instance/organization_settings` with that instance's secret key: *Membership required*, automatic first organization, admin deletion off;123- the OAuth settings, `GET /v1/instance/oauth_application_settings` (§ MCP OAuth);124- sign-in methods, legal consent, self-deletion and social providers, from the instance's public settings, `GET https://<frontend API host>/v1/environment`, which needs no key;125- a screenshot for the rest: *Roles* (each role's name and key, and who holds *Manage billing*), *Test mode* on (development only), *Webhooks* (the endpoint and its events, once the personal-data trigger fires).126127`npx clerk config pull --instance <dev|prod>` prints an instance's configuration as JSON as well (Clerk CLI 4.0.0, read `2026-10-25`). **A screenshot records intended configuration, not the live value.** Read the live value back before relying on it.128129## MCP OAuth130131**Apply these OAuth settings only for a member-authenticated MCP server.** Outside agents must reach it as signed-in members, with Clerk as authorization server. This section holds only Clerk settings. Apply `mcp-server` for callers, the route, limits, tools, directories, clients and package. That skill also covers agent-started sign-up through *Create first organization automatically*, an organization setting rather than an OAuth one.132133Use *OAuth applications → Settings* (observed `2026-10-06`); these settings can fail silently.134135- **Create no OAuth application by hand.** MCP clients register themselves (DCR) or identify by a metadata URL (CIMD). Clerk says a DCR client appears under *OAuth applications → Applications* after its first sign-in. A CIMD client may not appear at all (Backend API observed `2026-10-27`; the dashboard was not checked). A manual application is only for a client that can do neither. It needs the consent screen on and the same scopes, because instance defaults do not rewrite its scopes.136- **Enable CIMD support and admit any compatible CIMD client.** Set Client admission to *Any compatible CIMD client*. That is `client_id_metadata_documents_advertised` `true`, with `client_id_metadata_documents_only_allow_pre_registered_clients` and `client_id_metadata_documents_block_implicitly_allowed_clients` both `false`. When the switch goes on, the dashboard preselects *pre-registered and previously connected clients*, which refuses every new client.137- **Enable published DCR support even though Clerk labels it deprecated.** Set `dynamic_oauth_client_registration` on; Clerk labels it *Deprecated*. Many MCP clients still register only through DCR.138- **Set default scopes for identity and, where applicable, organizations.** Use `openid`, `profile`, `email`, plus `user:org:read` in the organization shape.139 - Without `user:org:read`, the consent screen asks for no organization, and every connection is refused `organization_required`.140 - The dashboard shows `offline_access` and will not remove it. It is not stored in `default_scopes`, and it only lets a client that asks for it refresh. ChatGPT asks for it (observed `2026-10-27`).141- **Require PKCE.** Turn `pkce_required` on.142- **Enable JWT access tokens and include the audience.** Turn on `oauth_jwt_access_tokens` and *Include Audience* (`aud_claim_enabled`, off by default).143 - The route requires its own exact URL as the resource in `aud`: `<APP_URL>/api/mcp` by default, or the path the product chose instead (one product mounts it at `/mcp`).144 - The protected-resource metadata describes that path, never the origin root.145- **Apply, then re-read.** Use `PATCH`, then `GET /v1/instance/oauth_application_settings`, with that instance's own secret key. Record the re-read in the integration notes: development and production separately, dated.146- **An instance cloned from development does not carry these settings.** (Observed `2026-10-24`.) Apply and re-read them on the clone as on any new instance.147- **No new environment variable.** The publishable key gives the issuer, the secret key verifies tokens and reads membership, and `APP_URL` gives the resource and the discovery URLs.148149**Allow for all four OAuth verification behaviours in the route.**150151- **Discovery's `claims_supported` is not the shape of the JWT Clerk emits.** The list omits `client_id` and `scope`, which a real grant can carry. Run a real DCR + PKCE grant before changing which claims the route requires.152- **A JWKS or network failure while verifying is a retryable `503`, never an invalid-token `401`.** A `401` sends the client back through the whole OAuth flow.153- **An unknown `kid` never reaches Clerk's verifier.** Given a `kid` it has not cached, `verifyToken` fetches the JWKS from the Backend API with the secret key, and an unauthenticated caller chooses the `kid`. Check the unverified header's `kid` against the key list last loaded, refresh that list at most once a minute, and refuse the rest as invalid.154- **Offline JWT verification does not see a revoked grant until the token expires.** It remains unseen until token expiry, a day by default. Recheck workspace access on every request through `requireWorkspaceAccess`, never from the token's claims alone.155156Each rule's origin, the case that taught it, is in `receipts.md` beside this file; read it when a rule's edge is unclear.157158## How you can tell it worked159160A new user signs up on a phone against production and lands where they should, in the right organization and role. The served pages carry the production publishable key.161162## Files163164| File | Holds | Read when |165|---|---|---|166| `references/sessions-and-front-door.md` | the session seam; ids only; the sign-in surface and redirects; the front door and the member home: the rule, its shape on this stack, what was rejected, the tests that pin it | adding sign-in; touching the root layout, a public page, the member home or a redirect |167| `references/organizations-and-billing.md` | organizations and the choose-organization task; roles and *Manage billing*; the organization modal and custom pages; Clerk Billing: the billing file and the CLI, in code (callers with no session included) and in tests; pricing; webhooks, personal data and Clerk's own deletion paths | adding organizations, a role, a plan, a limit, pricing or a deletion webhook |168| `references/csp-and-variables.md` | the nonce CSP and static headers; every Clerk variable and the env schema's Clerk checks; what to record; the production instance | adding a CSP or a third-party origin; adding or checking a Clerk key; going live |169| `references/authenticated-mile.md` | Clerk's half of a real-session browser suite: Test mode, test accounts, the testing token, organizations in `globalSetup`, signing in through `<SignIn />`, the signed-out-action trap, locators | writing or debugging an authenticated end-to-end test |170| `references/gotchas.md` | every Clerk gotcha, each with its symptom and receipt | before touching Clerk; when sign-in or an authenticated action seems to do nothing |171172## When something is learned173174- **Keep general Clerk lessons here with their receipts.** Include the date, what happened, the product named by kind.175- **Date what Clerk did or required.** Use "observed 2026-10", because the dashboard and its labels change without notice. When one changes, correct the line; never leave the old one beside the new.176- **Keep product-specific facts in its own integration notes.** This includes its instances, roles, slugs, confirmations and re-reads.