feat(jwt): allow custom jwks endpoint (#6269)

Author: luist18

docs/content/docs/plugins/jwt.mdx

@@ -239,6 +239,57 @@ jwt({
 })
 ```
 
+### Custom JWKS Path
+
+By default, the JWKS endpoint is available at `/jwks`. You can customize this path using the `jwksPath` option.
+
+This is useful when you need to:
+- Follow OAuth 2.0/OIDC conventions (e.g., `/.well-known/jwks.json`)
+- Match existing API conventions in your application
+- Avoid path conflicts with other endpoints
+
+**Server Configuration:**
+
+```ts title="auth.ts"
+jwt({
+  jwks: {
+    jwksPath: "/.well-known/jwks.json"
+  }
+})
+```
+
+**Client Configuration:**
+
+When using a custom `jwksPath` on the server, you **MUST** configure the client with the same path:
+
+```ts title="auth-client.ts"
+import { createAuthClient } from "better-auth/client"
+import { jwtClient } from "better-auth/client/plugins"
+
+export const authClient = createAuthClient({
+  plugins: [
+    jwtClient({
+      jwks: {
+        jwksPath: "/.well-known/jwks.json" // Must match server configuration
+      }
+    })
+  ]
+})
+```
+
+Then you can use the `jwks()` method as usual:
+
+```ts
+const { data, error } = await authClient.jwks()
+if (data) {
+  // Use data.keys to verify JWT tokens
+}
+```
+
+<Callout type="warning">
+  The `jwksPath` configured on the client **MUST** match the server configuration. If they don't match, the client will not be able to fetch the JWKS.
+</Callout>
+
 ### Custom Signing
 
 This is an advanced feature. Configuration outside of this plugin **MUST** be provided.

packages/better-auth/src/plugins/jwt/client.ts

@@ -1,9 +1,35 @@
 import type { BetterAuthClientPlugin } from "@better-auth/core";
+import type { JSONWebKeySet } from "jose";
 import type { jwt } from "./index";
 
-export const jwtClient = () => {
+interface JwtClientOptions {
+	jwks?: {
+		/**
+		 * The path of the endpoint exposing the JWKS.
+		 * Must match the server configuration.
+		 *
+		 * @default /jwks
+		 */
+		jwksPath?: string;
+	};
+}
+
+export const jwtClient = (options?: JwtClientOptions) => {
+	const jwksPath = options?.jwks?.jwksPath ?? "/jwks";
+
 	return {
 		id: "better-auth-client",
 		$InferServerPlugin: {} as ReturnType<typeof jwt>,
+		pathMethods: {
+			[jwksPath]: "GET",
+		},
+		getActions: ($fetch) => ({
+			jwks: async (fetchOptions?: any) => {
+				return await $fetch<JSONWebKeySet>(jwksPath, {
+					method: "GET",
+					...fetchOptions,
+				});
+			},
+		}),
 	} satisfies BetterAuthClientPlugin;
 };

packages/better-auth/src/plugins/jwt/index.ts

@@ -36,12 +36,25 @@ export const jwt = (options?: JwtOptions | undefined) => {
 		);
 	}
 
+	const jwksPath = options?.jwks?.jwksPath ?? "/jwks";
+	if (
+		typeof jwksPath !== "string" ||
+		jwksPath.length === 0 ||
+		!jwksPath.startsWith("/") ||
+		jwksPath.includes("..")
+	) {
+		throw new BetterAuthError(
+			"jwks_config",
+			"jwksPath must be a non-empty string starting with '/' and not contain '..'",
+		);
+	}
+
 	return {
 		id: "jwt",
 		options,
 		endpoints: {
 			getJwks: createAuthEndpoint(
-				"/jwks",
+				jwksPath,
 				{
 					method: "GET",
 					metadata: {

packages/better-auth/src/plugins/jwt/jwt.test.ts

@@ -743,3 +743,36 @@ describe("jwt - custom adapter", async () => {
 		expect(storage.length).toBe(1);
 	});
 });
+
+describe("jwt - custom jwksPath", async () => {
+	it("should use custom jwksPath when specified", async () => {
+		const { auth } = await getTestInstance({
+			plugins: [
+				jwt({
+					jwks: {
+						jwksPath: "/.well-known/jwks.json",
+					},
+				}),
+			],
+		});
+
+		const client = createAuthClient({
+			plugins: [jwtClient({ jwks: { jwksPath: "/.well-known/jwks.json" } })],
+			baseURL: "http://localhost:3000/api/auth",
+			fetchOptions: {
+				customFetchImpl: async (url, init) => {
+					return auth.handler(new Request(url, init));
+				},
+			},
+		});
+
+		const jwks = await client.jwks();
+		expect(jwks.error).toBeNull();
+		expect(jwks.data?.keys).toBeDefined();
+		expect(jwks.data?.keys.length).toBeGreaterThan(0);
+
+		// Verify old /jwks endpoint is not found
+		const oldJwks = await client.$fetch<JSONWebKeySet>("/jwks");
+		expect(oldJwks.error?.status).toBe(404);
+	});
+});

packages/better-auth/src/plugins/jwt/types.ts

@@ -42,6 +42,15 @@ export interface JwtOptions {
 				 * @default 2592000 (30 days)
 				 */
 				gracePeriod?: number;
+				/**
+				 * The path of the endpoint exposing the JWKS.
+				 * When set, this replaces the default /jwks endpoint.
+				 * The old endpoint will return 404.
+				 *
+				 * @default /jwks
+				 * @example "/.well-known/jwks.json"
+				 */
+				jwksPath?: string;
 		  }
 		| undefined;