docs: update dynamic authentication guide with custom fetcher approach

- Add custom fetcher middleware as recommended approach per Swimburger feedback
- Replace Proxy pattern with simpler method override alternative
- Add comprehensive gotchas and security considerations
- Update all examples to use plant-themed content (PlantStoreClient, plants.get, etc.)
- Fix Vale linting issues: remove time-relative 'now', define HMAC acronym
- Add allowCustomFetcher configuration example
- Include token memoization pattern with grace period
- Document import paths, header merging, and thread safety considerations

Co-Authored-By: Chris McDonnell <[email protected]>

Author: devin-ai-integration[bot]

fern/products/sdks/guides/dynamic-authentication.mdx

@@ -3,73 +3,92 @@ title: Dynamic authentication
 description: Implement dynamic authentication patterns like short-lived JWT signing in your SDKs.
 ---
 
-Your API may require dynamic authentication where credentials need to be generated or refreshed for each request, such as signing short-lived JWTs or rotating tokens. Fern-generated SDKs support this pattern through request-level header injection.
+Your API may require dynamic authentication where credentials need to be generated or refreshed for each request, such as signing short-lived JWTs or rotating tokens. Fern-generated SDKs support this pattern through custom fetcher middleware.
 
-## How it works
+## Recommended: Custom fetcher middleware
 
-Fern-generated SDKs accept a `headers` parameter in the `RequestOptions` for every API call. This allows you to inject dynamically computed headers (like signed JWTs) on a per-request basis without needing to override each method.
+The best way to implement dynamic authentication in TypeScript SDKs is to use a custom fetcher. This acts as middleware for all requests, allowing you to inject authentication logic in a single place without overriding individual methods.
 
-## TypeScript example: Short-lived JWT signing
+### How it works
 
-Here's how to implement a client wrapper that signs a JWT valid for 15 seconds before each request:
+When you enable `allowCustomFetcher` in your generator configuration, the generated SDK accepts a `fetcher` parameter in the client options. This fetcher wraps all HTTP requests, giving you a single injection point for authentication logic.
+
+### TypeScript example: Short-lived JWT signing
+
+Here's how to implement JWT signing with token memoization:
 
 <Steps>
 
-### Create a wrapper client
+### Enable custom fetcher in generator configuration
+
+Add `allowCustomFetcher: true` to your `generators.yml`:
+
+```yaml title="generators.yml"
+default-group: local
+groups:
+  local:
+    generators:
+      - name: fernapi/fern-typescript-node-sdk
+        version: 0.x.x
+        output:
+          location: local-file-system
+          path: ../generated/typescript
+        config:
+          allowCustomFetcher: true
+```
+
+### Create a custom fetcher with JWT signing
 
-Create a custom client class that extends the generated Fern client and adds JWT signing logic:
+Create a fetcher function that wraps the default fetcher and injects JWT authentication:
 
-```typescript title="src/wrapper/MyClient.ts"
-import { MyClient as FernClient } from "../Client";
+```typescript title="src/wrapper/jwtFetcher.ts"
 import * as jwt from "jsonwebtoken";
+import { fetcher as defaultFetcher, type FetchFunction } from "../core/fetcher";
 
-export class MyClient extends FernClient {
-  private privateKey: string;
+export function createJwtFetcher(privateKey: string): FetchFunction {
+  // Cache token to avoid regenerating on every request
+  let cachedToken: { value: string; expiresAt: number } | undefined;
 
-  constructor(options: { privateKey: string; environment: string }) {
-    super({
-      environment: options.environment,
-    });
-    this.privateKey = options.privateKey;
-  }
-
-  /**
-   * Generate a short-lived JWT token valid for 15 seconds
-   */
-  private generateJWT(): string {
+  return async (args) => {
     const now = Math.floor(Date.now() / 1000);
-    const payload = {
-      iat: now,
-      exp: now + 15, // Expires in 15 seconds
-    };
 
-    return jwt.sign(payload, this.privateKey, { algorithm: "RS256" });
-  }
-
-  /**
-   * Helper method to inject JWT into request options
-   */
-  private withJWT(requestOptions?: any): any {
-    const token = this.generateJWT();
-    return {
-      ...requestOptions,
-      headers: {
-        ...requestOptions?.headers,
-        Authorization: `Bearer ${token}`,
-      },
+    // Regenerate token if expired or about to expire (within 2 seconds)
+    if (!cachedToken || cachedToken.expiresAt - 2 <= now) {
+      const payload = {
+        iat: now,
+        exp: now + 15, // Token valid for 15 seconds
+      };
+      const token = jwt.sign(payload, privateKey, { algorithm: "RS256" });
+      cachedToken = { value: token, expiresAt: payload.exp };
+    }
+
+    // Inject JWT into request headers
+    const headers = {
+      ...(args.headers ?? {}),
+      Authorization: `Bearer ${cachedToken.value}`,
     };
-  }
 
-  // Override methods to automatically inject JWT
-  async getUser(userId: string, requestOptions?: any) {
-    return super.getUser(userId, this.withJWT(requestOptions));
-  }
+    // Call the default fetcher with modified headers
+    return defaultFetcher({ ...args, headers });
+  };
+}
+```
 
-  async createUser(request: any, requestOptions?: any) {
-    return super.createUser(request, this.withJWT(requestOptions));
-  }
+### Create a wrapper client
 
-  // Add overrides for all other methods...
+Extend the generated client to use the custom fetcher:
+
+```typescript title="src/wrapper/PlantStoreClient.ts"
+import { PlantStoreClient as FernClient } from "../Client";
+import { createJwtFetcher } from "./jwtFetcher";
+
+export class PlantStoreClient extends FernClient {
+  constructor(options: { privateKey: string; environment: string }) {
+    super({
+      environment: options.environment,
+      fetcher: createJwtFetcher(options.privateKey),
+    });
+  }
 }
 ```
 
@@ -78,7 +97,7 @@ export class MyClient extends FernClient {
 Update your `index.ts` to export the wrapper instead of the generated client:
 
 ```typescript title="src/index.ts"
-export { MyClient } from "./wrapper/MyClient";
+export { PlantStoreClient } from "./wrapper/PlantStoreClient";
 export * from "./api"; // Export types
 ```
 
@@ -93,75 +112,42 @@ Protect your custom code from being overwritten:
 
 ### Use the client
 
-Your users can now use the client with automatic JWT signing:
+Users can use the client with automatic JWT signing on all requests:
 
 ```typescript
-import { MyClient } from "my-sdk";
+import { PlantStoreClient } from "plant-store-sdk";
 
-const client = new MyClient({
+const client = new PlantStoreClient({
   privateKey: process.env.PRIVATE_KEY,
-  environment: "https://api.example.com",
+  environment: "https://api.plantstore.com",
 });
 
 // JWT is automatically signed and injected for each request
-const user = await client.getUser("user-123");
-const newUser = await client.createUser({ name: "Alice" });
+const plant = await client.plants.get("monstera-123");
+const newPlant = await client.plants.create({ 
+  name: "Fiddle Leaf Fig",
+  species: "Ficus lyrata" 
+});
 ```
 
 </Steps>
 
-## Alternative: Proxy pattern without method overrides
+## Alternative: Method overrides
 
-If you want to avoid overriding each method individually, you can use a Proxy to intercept all method calls:
+If you cannot enable `allowCustomFetcher` or prefer a simpler approach, you can override individual methods:
 
-```typescript title="src/wrapper/MyClient.ts"
-import { MyClient as FernClient } from "../Client";
+```typescript title="src/wrapper/PlantStoreClient.ts"
+import { PlantStoreClient as FernClient } from "../Client";
 import * as jwt from "jsonwebtoken";
 
-export class MyClient {
-  private client: FernClient;
+export class PlantStoreClient extends FernClient {
   private privateKey: string;
 
   constructor(options: { privateKey: string; environment: string }) {
-    this.client = new FernClient({
+    super({
       environment: options.environment,
     });
     this.privateKey = options.privateKey;
-
-    // Return a proxy that intercepts all method calls
-    return new Proxy(this, {
-      get(target, prop) {
-        // If accessing the client property itself, return it
-        if (prop === "client" || prop === "privateKey") {
-          return target[prop as keyof typeof target];
-        }
-
-        // Get the property from the underlying client
-        const value = (target.client as any)[prop];
-
-        // If it's a function, wrap it to inject JWT
-        if (typeof value === "function") {
-          return function (...args: any[]) {
-            // The last argument is typically requestOptions
-            const lastArg = args[args.length - 1];
-            const isRequestOptions =
-              lastArg && typeof lastArg === "object" && !Array.isArray(lastArg);
-
-            if (isRequestOptions) {
-              // Inject JWT into existing request options
-              args[args.length - 1] = target.withJWT(lastArg);
-            } else {
-              // Add JWT as new request options
-              args.push(target.withJWT());
-            }
-
-            return value.apply(target.client, args);
-          };
-        }
-
-        return value;
-      },
-    });
   }
 
   private generateJWT(): string {
@@ -183,22 +169,33 @@ export class MyClient {
       },
     };
   }
+
+  // Override each method to inject JWT
+  async getPlant(plantId: string, requestOptions?: any) {
+    return super.plants.get(plantId, this.withJWT(requestOptions));
+  }
+
+  async createPlant(request: any, requestOptions?: any) {
+    return super.plants.create(request, this.withJWT(requestOptions));
+  }
+
+  // Override additional methods as needed...
 }
 ```
 
-This approach automatically wraps all methods without needing to override each one individually.
+<Note>This approach requires overriding each method individually, which can be tedious for large APIs. The custom fetcher approach is recommended for better maintainability.</Note>
 
 ## Python example: Short-lived JWT signing
 
-For Python SDKs, you can use a similar pattern:
+For Python SDKs, you can use a similar method override pattern:
 
 ```python title="src/wrapper/client.py"
-from .client import Client as FernClient
+from .client import PlantStoreClient as FernClient
 import jwt
 import time
 from typing import Optional, Dict, Any
 
-class Client(FernClient):
+class PlantStoreClient(FernClient):
     def __init__(self, *, private_key: str, environment: str):
         super().__init__(environment=environment)
         self._private_key = private_key
@@ -221,28 +218,59 @@ class Client(FernClient):
         options["headers"] = headers
         return options
 
-    def get_user(self, user_id: str, *, request_options: Optional[Dict[str, Any]] = None):
-        return super().get_user(user_id, request_options=self._with_jwt(request_options))
+    def get_plant(self, plant_id: str, *, request_options: Optional[Dict[str, Any]] = None):
+        return super().plants.get(plant_id, request_options=self._with_jwt(request_options))
 
-    def create_user(self, request: Any, *, request_options: Optional[Dict[str, Any]] = None):
-        return super().create_user(request, request_options=self._with_jwt(request_options))
+    def create_plant(self, request: Any, *, request_options: Optional[Dict[str, Any]] = None):
+        return super().plants.create(request, request_options=self._with_jwt(request_options))
 ```
 
 ## Other authentication patterns
 
 This same pattern works for other dynamic authentication scenarios:
 
 - **OAuth token refresh**: Automatically refresh expired access tokens before each request
-- **HMAC signing**: Sign requests with HMAC signatures based on request content
+- **HMAC (Hash-based Message Authentication Code) signing**: Sign requests with HMAC signatures based on request content
 - **Rotating API keys**: Switch between multiple API keys based on rate limits
 - **Time-based tokens**: Generate tokens that include timestamps or nonces
 
-## Best practices
+## Important considerations
 
-- **Cache when possible**: If your tokens are valid for longer periods, cache them to avoid regenerating on every request
-- **Handle errors gracefully**: Implement retry logic for authentication failures
+### Custom fetcher requirements
+
+- **Generator configuration**: The `allowCustomFetcher` option must be enabled in your `generators.yml` for the `fetcher` parameter to be available in `BaseClientOptions`
+- **Import path**: Import the default fetcher from `../core/fetcher` (or the appropriate path in your generated SDK) to wrap it with your custom logic
+- **Preserve all arguments**: When wrapping the default fetcher, ensure you pass through all arguments to maintain compatibility with the SDK's internal behavior
+
+### Security considerations
+
+- **Server-side only**: Never expose private keys in browser environments. JWT signing with private keys should only be done in server-side code (Node.js, Deno, Bun)
 - **Secure key storage**: Never hardcode private keys; use environment variables or secure key management systems
-- **Test thoroughly**: Ensure your wrapper handles all edge cases, including concurrent requests
+- **Avoid double authentication**: If your API already uses bearer token authentication in the Fern definition, be careful not to override the existing `Authorization` header. Consider using a different header name or conditionally setting the header
+
+### Performance and concurrency
+
+- **Token memoization**: Cache tokens to avoid regenerating them on every request. The example above caches tokens and refreshes them 2 seconds before expiration
+- **Thread safety**: The memoization pattern shown is safe for concurrent requests in JavaScript's single-threaded event loop, but be mindful of race conditions in other environments
+- **Grace period**: Refresh tokens slightly before they expire (e.g., 2 seconds early) to avoid edge cases where a token expires during request processing
+
+### Header merging
+
+- **Preserve existing headers**: When injecting authentication headers, always spread existing headers to avoid overwriting headers set by the SDK or user
+- **Header precedence**: Headers are merged in order: SDK defaults → client options → request options → custom fetcher. Your custom fetcher runs last and can override previous headers
+
+### Time synchronization
+
+- **Clock drift**: Be aware of potential clock drift between your client and server. Consider adding tolerance to your token expiration checks
+- **Timestamp precision**: Use Unix timestamps (seconds since epoch) for `iat` and `exp` claims to match JWT standards
+
+## Best practices
+
+- **Use custom fetcher for TypeScript**: The custom fetcher approach is the most maintainable solution for TypeScript SDKs when `allowCustomFetcher` is available
+- **Cache tokens appropriately**: Balance between security (shorter token lifetime) and performance (less frequent regeneration)
+- **Handle errors gracefully**: Implement retry logic for authentication failures and token refresh errors
+- **Test thoroughly**: Ensure your wrapper handles all edge cases, including concurrent requests, token expiration, and network failures
+- **Monitor token usage**: Log token generation and refresh events to help debug authentication issues in production
 
 ## See also