From 6ef33ce9ae4af2e136c10173817a941341f9320f Mon Sep 17 00:00:00 2001
From: Niels Kaspers <kaspersniels@gmail.com>
Date: Mon, 18 May 2026 09:10:14 +0300
Subject: [PATCH] docs(client): clarify private_key_jwt claims behavior

---
 packages/client/src/client/authExtensions.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/packages/client/src/client/authExtensions.ts b/packages/client/src/client/authExtensions.ts
index c366947bee..b4973fb4dd 100644
--- a/packages/client/src/client/authExtensions.ts
+++ b/packages/client/src/client/authExtensions.ts
@@ -31,6 +31,13 @@ export function createPrivateKeyJwtAuth(options: {
     alg: string;
     audience?: string | URL;
     lifetimeSeconds?: number;
+    /**
+     * Additional custom JWT claims to include in the signed assertion.
+     *
+     * These are merged into the JWT payload, but the standard JWT claims
+     * (`iss`, `sub`, `aud`, `exp`, `iat`, `jti`) are always set explicitly by the SDK and
+     * will override any overlapping keys provided here.
+     */
     claims?: Record<string, unknown>;
 }): AddClientAuthentication {
     return async (_headers, params, url, metadata) => {