docs: add Clerk setup guide (#993)

wdawson · claude · github-actions[bot] · web-flow · commit 35ccdd13e644 · 2026-06-03T11:36:30.000-03:00
* docs: add Clerk setup guide for User Sources (GRO-98) Fifth per-provider page under /guides/user-sources/, modeled on the Microsoft Entra ID, Okta, Auth0, and Stytch pages. Walks an admin through creating an OAuth application in the Clerk Dashboard's Configure → Developers → OAuth Applications section, then pasting the resulting Client ID, Client Secret, and Frontend API URL into Arcade's User Source form. Clerk-specific decisions: - Issuer URL is the Frontend API URL with NO trailing slash. Empirically verified against `probable-akita-28.clerk.accounts.dev` (Wils's test instance): the discovery doc reports `issuer: https://probable-akita-28.clerk.accounts.dev` with no trailing slash. Different from Auth0 (which uses one). - Document both development and production Frontend API URL formats (`<verb-noun-NN>.clerk.accounts.dev` vs `clerk.<your-app-domain>.com`). Per Clerk's docs, dev and prod instances are separate so each needs its own OAuth application and Arcade User Source. - Subject Claim recommendation `sub` (Clerk user ID). Mention Clerk's `public_metadata` / `private_metadata` scopes for adding custom data to claims without needing a custom-claim template. - Default scope set (`openid profile email`) is supported. Clerk also has `offline_access`, `public_metadata`, `private_metadata` if needed. Nav path verified with Wils: Workspace → Application → Configure tab → Developers → OAuth Applications (or → API keys for the Frontend API URL). Screenshots intentionally not yet included — captured separately by Wils from his test instance and will wire up in a follow-up commit on this branch. Add `Clerk` to the Arcade Vale vocabulary. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * 🤖 Regenerate LLMs.txt * docs: refine Clerk page from real dashboard captures + new guidance Major revisions after seeing the real Clerk dashboard: - The Create application dialog has Name, Scopes, and two toggles: Public and Consent screen. It does not have a Redirect URIs field (those are configured on the application's settings page after creation). Restructure the Steps to match. - Spell out the toggle states explicitly: - Public OFF: Arcade authenticates with a Client Secret. The confidential flow still uses PKCE; the toggle only controls whether Clerk requires a Client Secret on token exchange. Verified: Clerk's discovery doc reports `code_challenge_methods_supported: ['S256']` on all clients. - Consent screen OFF: A User Source-backed gateway is part of the customer's own identity infrastructure, so the extra consent prompt isn't appropriate. - openid is not selected by default in Clerk's Scopes dropdown; admins have to add it. Call this out explicitly. - Issuer URL lookup moves to the OAuth application's own Configure page (Application configuration URLs -> Discovery URL), with the /.well-known/openid-configuration suffix stripped. Same place as the Client ID and the Redirect URIs configuration, so admins don't need to navigate to a separate API keys page. - Emphasize "no trailing slash" on the Issuer URL since Clerk's emitted issuer omits it. Add two light-mode screenshots from Wils's test instance: - Create application dialog - Configure page showing Redirect URIs + Client ID + Discovery URL Per Wils, the client-secret one-time dialog screenshot is skipped -- it's a transient view and the prose covers what to do. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: drop unused client secret screenshot from Clerk page Per Wils — the one-time client secret dialog is transient and doesn't need a screenshot. Cleaning up the unreferenced file I committed in the previous round. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Mateo Torres <mateo@arcade.dev>
diff --git a/app/en/guides/user-sources/_meta.tsx b/app/en/guides/user-sources/_meta.tsx
@@ -7,6 +7,9 @@ export const meta: MetaRecord = {
   auth0: {
     title: "Auth0",
   },
+  clerk: {
+    title: "Clerk",
+  },
   "microsoft-entra-id": {
     title: "Microsoft Entra ID",
   },
diff --git a/app/en/guides/user-sources/clerk/page.mdx b/app/en/guides/user-sources/clerk/page.mdx
@@ -0,0 +1,92 @@
+---
+title: "Clerk"
+description: "Use Clerk as a User Source so people who already sign in through your Clerk instance can sign in to your MCP Gateways"
+---
+
+import Image from "next/image";
+import { Steps } from "nextra/components";
+
+export const IMAGE_SCALE_FACTOR = 1.5;
+export const CLERK_SCREENSHOT_WIDTH = 1312 / IMAGE_SCALE_FACTOR;
+export const CLERK_SCREENSHOT_HEIGHT = 949 / IMAGE_SCALE_FACTOR;
+
+# Clerk
+
+Use Clerk as a User Source so the people who already sign in through your Clerk instance can sign in to your MCP Gateways. Clerk's [OAuth applications](https://clerk.com/docs/advanced-usage/clerk-idp) feature turns your Clerk instance into an OIDC identity provider that Arcade can connect to. Once you have the values it tells you to copy, [create the User Source in Arcade](/guides/user-sources#create-a-user-source).
+
+## Before you start
+
+- A Clerk account with admin access to the instance you want to use.
+- A Clerk instance. Clerk maintains separate development and production instances per app, each with its own Frontend API URL. You can develop against the development instance first and switch the User Source to the production instance when you're ready.
+- An Arcade project where you'll create the User Source.
+
+## Register an OAuth application in Clerk
+
+<Steps>
+
+### Open the Clerk Dashboard
+
+Sign in to the [Clerk Dashboard](https://dashboard.clerk.com/sign-in). Pick the workspace that owns your Clerk application, open the application you want to configure, then in the application's top tabs select **Configure**. In the left navigation under **Developers**, click **OAuth Applications**, then **Add OAuth application**.
+
+### Fill in the application details
+
+In the **Create application** dialog:
+
+- **Name**: a label your team will recognize, for example `Arcade User Source`.
+- **Scopes**: open the Scopes dropdown and make sure `openid` is selected. Arcade also requests `profile` and `email` by default, so add those if they aren't selected already.
+- **Public**: leave this toggle **off**. Arcade authenticates with Clerk using a Client Secret, which the confidential flow supports. Arcade still uses PKCE on every sign-in regardless of this setting; the toggle only controls whether Clerk requires a Client Secret on token exchange.
+- **Consent screen**: leave this toggle **off**. Clerk recommends enabling consent for third-party applications, but a User Source-backed gateway is part of your own identity infrastructure, so end users shouldn't see an extra consent prompt at sign-in.
+
+Click **Add**.
+
+<Image
+  alt="Create application dialog in Clerk with Name and Scopes filled in and the Public and Consent screen toggles off"
+  className="max-w-full mt-4"
+  src="/images/user-sources/clerk/clerk-create-app-light.png"
+  width={CLERK_SCREENSHOT_WIDTH}
+  height={CLERK_SCREENSHOT_HEIGHT}
+/>
+
+### Save the Client Secret
+
+Clerk shows the **Client Secret** in a one-time dialog after the application is created. Copy the value and store it somewhere secure. The full secret is not retrievable from the Dashboard afterward; if you lose it, regenerate a new one from the application's settings.
+
+### Add the Arcade redirect URL
+
+After closing the secret dialog, Clerk takes you to the application's settings page. In the **Redirect URIs** section, click **Add URI** and enter:
+
+`https://cloud.arcade.dev/oauth2/intermediate_callback`
+
+The same page also surfaces your **Client ID** under **Application credentials** and your **Discovery URL** under **Application configuration URLs** — you'll use both in the next section.
+
+<Image
+  alt="Clerk OAuth application Configure page with the Arcade redirect URI added and the Client ID and Discovery URL visible"
+  className="max-w-full mt-4"
+  src="/images/user-sources/clerk/clerk-redirect-uri-client-id-issuer-light.png"
+  width={CLERK_SCREENSHOT_WIDTH}
+  height={CLERK_SCREENSHOT_HEIGHT}
+/>
+
+</Steps>
+
+## Copy these values to Arcade
+
+Copy these values into Arcade's User Source form:
+
+| Arcade field | Where to find it in Clerk |
+|---|---|
+| **Issuer URL** | The OAuth application's **Discovery URL** under **Application configuration URLs**, with the `/.well-known/openid-configuration` suffix removed. For example, `https://<verb-noun-NN>.clerk.accounts.dev/.well-known/openid-configuration` becomes `https://<verb-noun-NN>.clerk.accounts.dev`. **Do not add a trailing slash.** Clerk emits the issuer without one and Arcade matches the value exactly. |
+| **Client ID** | The **Client ID** field under **Application credentials**. |
+| **Client Secret** | The Client Secret you saved when you created the application. |
+
+## Create the User Source in Arcade
+
+Open the Arcade Dashboard, select your project, navigate to **User Sources**, and click **Create User Source**. Paste the values from the table above. For a walkthrough of the form, see [Create a User Source](/guides/user-sources#create-a-user-source) in the User Sources overview.
+
+Once the User Source is active, attach it to an MCP Gateway by following [Create via Dashboard](/guides/mcp-gateways/create-via-dashboard) and picking **User Source** under "Non-Arcade Users" in the gateway form.
+
+## Notes
+
+- **Development vs production instances**: Clerk's development and production instances have different Frontend API URLs and different OAuth applications. When you're ready to move from a development setup to production, register a new OAuth application in the production instance and create a separate Arcade User Source for it.
+- **Client secret rotation**: Clerk supports regenerating the Client Secret from the OAuth application's **Application credentials** section. See [Rotate the client secret](/guides/user-sources#rotate-the-client-secret) in the User Sources guide for the Arcade-side procedure.
+- **Subject Claim**: Arcade's default Subject Claim, `sub`, is the Clerk user ID and is the recommended value. Clerk's OAuth applications also expose `public_metadata` and `private_metadata` scopes that surface the corresponding [user metadata](https://clerk.com/docs/users/metadata) on the ID token, which lets you add organization, role, or other custom data to claims. See [Advanced: scopes and subject claim](/guides/user-sources#advanced-scopes-and-subject-claim) in the overview for what makes a good claim.
diff --git a/public/images/user-sources/clerk/clerk-create-app-light.png b/public/images/user-sources/clerk/clerk-create-app-light.png
diff --git a/public/images/user-sources/clerk/clerk-redirect-uri-client-id-issuer-light.png b/public/images/user-sources/clerk/clerk-redirect-uri-client-id-issuer-light.png
diff --git a/public/llms.txt b/public/llms.txt
@@ -1,4 +1,4 @@
-<!-- git-sha: 2e2be3803117defc992bf4c2e5744a162c4ae6ff generation-date: 2026-06-02T23:31:22.193Z -->
+<!-- git-sha: 1713003ee9eb311132f7e93563edd85b2da42011 generation-date: 2026-06-02T23:47:34.646Z -->
 
 # Arcade
 
@@ -91,6 +91,7 @@ Arcade delivers three core capabilities: Deploy agents even your security team w
 - [Calling tools in your agent with Arcade](https://docs.arcade.dev/en/get-started/quickstarts/call-tool-agent): This documentation page provides a comprehensive guide on how to utilize Arcade to enable AI agents to call various hosted tools, such as sending emails or creating documents. Users will learn how to install the Arcade client, set up their environment, and implement workflows that leverage
 - [Capture mode](https://docs.arcade.dev/en/guides/create-tools/evaluate-tools/capture-mode): The "Capture mode" documentation page guides users on how to record tool calls without scoring, enabling them to bootstrap test expectations, debug model behavior, and explore new tools. By using the `--capture` flag with existing evaluation commands, users can easily
 - [Checking Tool Authorization Status](https://docs.arcade.dev/en/guides/tool-calling/custom-apps/check-auth-status): This documentation page provides a comprehensive guide on how to check the authorization status of tools before execution, helping users understand necessary permissions and tool availability. It includes instructions for initializing the client in Python or JavaScript, as well as methods for checking the authorization status
+- [Clerk](https://docs.arcade.dev/en/guides/user-sources/clerk): Documentation page
 - [Comparative evaluations](https://docs.arcade.dev/en/guides/create-tools/evaluate-tools/comparative-evaluations): The "Comparative Evaluations" documentation page provides users with the tools and guidance to compare different AI model implementations using isolated tool registries, known as tracks. It outlines how to set up and conduct evaluations to assess tool selection and performance across various contexts
 - [Compare MCP Server Types](https://docs.arcade.dev/en/guides/create-tools/tool-basics/compare-server-types): This documentation page provides a comparative overview of different MCP server types, detailing their functionalities based on transport methods and deployment options. Users can learn about the capabilities of each server type, including support for various tools and authentication methods, to help them choose the most
 - [Connect Arcade to your LLM](https://docs.arcade.dev/en/get-started/agent-frameworks/setup-arcade-with-your-llm-python): This documentation page guides users on how to connect Arcade to a Large Language Model (LLM) using Python by creating a "harness" that facilitates interaction between the user, the model, and various tools. Users will learn to set up an agent
diff --git a/styles/config/vocabularies/Arcade/accept.txt b/styles/config/vocabularies/Arcade/accept.txt
@@ -35,3 +35,4 @@ repo
 /mb-\d+/
 /ml-\d+/
 /mr-\d+/
+Clerk
