docs: reorganize dynamic authentication by language

- Remove 'Alternative: Method overrides' section from TypeScript docs
- Create TypeScript-specific page with custom fetcher approach only
- Create Python-specific page with method override approach
- Convert main guide to lightweight overview hub with language cards
- Add navigation entries for both language-specific pages
- Keep language-agnostic considerations in overview

Addresses Swimburger's feedback to organize content by language.

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

Author: devin-ai-integration[bot]

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

@@ -3,290 +3,54 @@ 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 custom fetcher middleware.
+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 language-specific approaches.
 
-## Recommended: Custom fetcher middleware
+## Language-specific guides
 
-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.
+Each language has its own recommended approach for implementing dynamic authentication:
 
-### How it works
+<Cards>
+  <Card title="TypeScript" icon="fa-brands fa-js" href="/sdks/generators/typescript/dynamic-authentication">
+    Use custom fetcher middleware to inject authentication logic in a single place for all requests. Supports JWT signing, OAuth token refresh, and more.
+  </Card>
+  <Card title="Python" icon="fa-brands fa-python" href="/sdks/generators/python/dynamic-authentication">
+    Use method overrides to inject authentication logic for each API call. Supports JWT signing, OAuth token refresh, and more.
+  </Card>
+</Cards>
 
-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.
+## Common use cases
 
-### TypeScript example: Short-lived JWT signing
-
-Here's how to implement JWT signing with token memoization:
-
-<Steps>
-
-### 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 fetcher function that wraps the default fetcher and injects JWT authentication:
-
-```typescript title="src/wrapper/jwtFetcher.ts"
-import * as jwt from "jsonwebtoken";
-import { fetcher as defaultFetcher, type FetchFunction } from "../core/fetcher";
-
-export function createJwtFetcher(privateKey: string): FetchFunction {
-  // Cache token to avoid regenerating on every request
-  let cachedToken: { value: string; expiresAt: number } | undefined;
-
-  return async (args) => {
-    const now = Math.floor(Date.now() / 1000);
-    
-    // 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}`,
-    };
-
-    // Call the default fetcher with modified headers
-    return defaultFetcher({ ...args, headers });
-  };
-}
-```
-
-### Create a wrapper client
-
-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";
-
-// Infer the exact options type from the generated client's constructor
-type FernClientOptions = ConstructorParameters<typeof FernClient>[0];
-// Accept all options except 'fetcher', and add our 'privateKey'
-type Options = Omit<FernClientOptions, "fetcher"> & { privateKey: string };
-
-export class PlantStoreClient extends FernClient {
-  constructor(options: Options) {
-    // Extract privateKey and pass all other options to the parent
-    const { privateKey, ...clientOptions } = options;
-    super({
-      ...clientOptions,
-      fetcher: createJwtFetcher(privateKey),
-    });
-  }
-}
-```
-
-<Note>
-This pattern uses `ConstructorParameters` to infer the exact options type from the generated client, ensuring compatibility with all client options (headers, timeoutInSeconds, maxRetries, etc.) without hardcoding them. This keeps the wrapper future-proof as the generator adds new options.
-</Note>
-
-### Export the wrapper client
-
-Update your `index.ts` to export the wrapper instead of the generated client:
-
-```typescript title="src/index.ts"
-export { PlantStoreClient } from "./wrapper/PlantStoreClient";
-export * from "./api"; // Export types
-```
-
-### Add to `.fernignore`
-
-Protect your custom code from being overwritten:
-
-```diff title=".fernignore"
-+ src/wrapper
-+ src/index.ts
-```
-
-### Use the client
-
-Users can use the client with automatic JWT signing on all requests:
-
-```typescript
-import { PlantStoreClient } from "plant-store-sdk";
-
-const client = new PlantStoreClient({
-  privateKey: process.env.PRIVATE_KEY,
-  environment: "https://api.plantstore.com",
-});
-
-// JWT is automatically signed and injected for each request
-const plant = await client.plants.get("monstera-123");
-const newPlant = await client.plants.create({ 
-  name: "Fiddle Leaf Fig",
-  species: "Ficus lyrata" 
-});
-```
-
-</Steps>
-
-## Alternative: Method overrides
-
-If you cannot enable `allowCustomFetcher` or prefer a simpler approach, you can override individual methods:
-
-```typescript title="src/wrapper/PlantStoreClient.ts"
-import { PlantStoreClient as FernClient } from "../Client";
-import * as jwt from "jsonwebtoken";
-
-type FernClientOptions = ConstructorParameters<typeof FernClient>[0];
-type Options = Omit<FernClientOptions, "fetcher"> & { privateKey: string };
-
-export class PlantStoreClient extends FernClient {
-  private privateKey: string;
-
-  constructor(options: Options) {
-    const { privateKey, ...clientOptions } = options;
-    super(clientOptions);
-    this.privateKey = privateKey;
-  }
-
-  private generateJWT(): string {
-    const now = Math.floor(Date.now() / 1000);
-    const payload = {
-      iat: now,
-      exp: now + 15,
-    };
-    return jwt.sign(payload, this.privateKey, { algorithm: "RS256" });
-  }
-
-  private withJWT(requestOptions?: any): any {
-    const token = this.generateJWT();
-    return {
-      ...requestOptions,
-      headers: {
-        ...requestOptions?.headers,
-        Authorization: `Bearer ${token}`,
-      },
-    };
-  }
-
-  // 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...
-}
-```
-
-<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 method override pattern:
-
-```python title="src/wrapper/client.py"
-from .client import PlantStoreClient as FernClient
-import jwt
-import time
-from typing import Optional, Dict, Any
-
-class PlantStoreClient(FernClient):
-    def __init__(self, *, private_key: str, environment: str):
-        super().__init__(environment=environment)
-        self._private_key = private_key
-    
-    def _generate_jwt(self) -> str:
-        """Generate a short-lived JWT token valid for 15 seconds"""
-        now = int(time.time())
-        payload = {
-            "iat": now,
-            "exp": now + 15,
-        }
-        return jwt.encode(payload, self._private_key, algorithm="RS256")
-    
-    def _with_jwt(self, request_options: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Inject JWT into request options"""
-        token = self._generate_jwt()
-        options = request_options or {}
-        headers = options.get("headers", {})
-        headers["Authorization"] = f"Bearer {token}"
-        options["headers"] = headers
-        return 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_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:
+Dynamic authentication is useful for several scenarios:
 
+- **Short-lived JWT signing**: Generate and sign JWTs that expire after a short period (e.g., 15 seconds) for enhanced security
 - **OAuth token refresh**: Automatically refresh expired access tokens before each request
 - **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
+- **Rotating API keys**: Switch between multiple API keys based on rate limits or other criteria
+- **Time-based tokens**: Generate tokens that include timestamps or nonces for replay protection
 
 ## Important considerations
 
-### 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
+When implementing dynamic authentication, keep these language-agnostic considerations in mind:
 
-- **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
-- **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
+### Security
 
-### Performance and concurrency
+- **Secure key storage**: Never hardcode private keys or secrets; use environment variables or secure key management systems
+- **Server-side only**: For JWT signing with private keys, ensure this is only done in server-side code, never in browser environments
+- **Avoid double authentication**: If your API already uses bearer token authentication in the Fern definition, be careful not to override existing authentication headers
 
-- **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
+### Performance
 
-### 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
+- **Token caching**: Cache tokens to avoid regenerating them on every request, balancing security (shorter token lifetime) with performance (less frequent regeneration)
+- **Grace period**: Refresh tokens slightly before they expire to avoid edge cases where a token expires during request processing
+- **Concurrency**: Be mindful of race conditions when caching tokens in multi-threaded environments
 
 ### 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
+- **Clock drift**: Be aware of potential clock drift between your client and server; consider adding tolerance to token expiration checks
+- **Timestamp precision**: Use Unix timestamps (seconds since epoch) for JWT `iat` and `exp` claims to match standards
 
 ## See also
 
-- [Adding custom code](/sdks/capabilities/custom-code) - Learn more about extending generated SDKs
+- [Adding custom code](/sdks/custom-code) - Learn more about extending generated SDKs
 - [TypeScript custom code](/sdks/generators/typescript/custom-code) - TypeScript-specific customization guide
 - [Python custom code](/sdks/generators/python/custom-code) - Python-specific customization guide