From 99724b5de1d9aeadce1140aaffe16ec1fe5982e1 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 17:09:37 +0000 Subject: [PATCH 1/7] docs: document optional-auth config flag for Python and TypeScript SDKs Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/sdks/generators/python/configuration.mdx | 6 ++++++ fern/products/sdks/generators/typescript/configuration.mdx | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/fern/products/sdks/generators/python/configuration.mdx b/fern/products/sdks/generators/python/configuration.mdx index 47036fd155..ccc756f843 100644 --- a/fern/products/sdks/generators/python/configuration.mdx +++ b/fern/products/sdks/generators/python/configuration.mdx @@ -184,6 +184,12 @@ When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`, When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `fern_examples/0.0.1 (linux; x86_64) Python/3.11.0`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. If `omit_fern_headers` is enabled, no `User-Agent` or platform headers are sent and this option has no effect. + +When enabled, client auth parameters (bearer token, basic auth username and password, header auth) remain optional even when the API spec mandates auth on every endpoint, and requests are sent without an auth header when no credential is provided. By default, the client raises an error when a mandatory credential is missing. Also accepted as `optional-auth` or `optionalAuth`. + +Enable this when callers authenticate through a mechanism other than the API's own scheme, such as cloud provider credentials, and would otherwise have to pass a placeholder value. + + This changes your declared python dependency, which is not meant to be done often if at all. This is a last resort if any dependencies force you to change your version requirements. diff --git a/fern/products/sdks/generators/typescript/configuration.mdx b/fern/products/sdks/generators/typescript/configuration.mdx index f9694f6160..7dabcfd1ce 100644 --- a/fern/products/sdks/generators/typescript/configuration.mdx +++ b/fern/products/sdks/generators/typescript/configuration.mdx @@ -409,6 +409,12 @@ When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`, When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `my-sdk/0.0.1 (linux; x86_64) Node/20.11.0`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. If `omitFernHeaders` is enabled, no `User-Agent` or platform headers are sent and this option has no effect. + +When enabled, client auth parameters (bearer token, basic auth credentials, header auth) remain optional even when the API spec mandates auth on every endpoint, and requests are sent without an auth header when no credential is provided. By default, the client throws when a mandatory credential is missing. + +Enable this when callers authenticate through a mechanism other than the API's own scheme, such as cloud provider credentials, and would otherwise have to pass a placeholder value. + + Controls the output format of generated files: - **When `true` (default)**: Outputs raw TypeScript `.ts` files From 58eb5692fdb03012931653e577c0d6650f22ffdd Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 30 Jul 2026 15:26:02 -0400 Subject: [PATCH 2/7] add cross references --- fern/products/sdks/deep-dives/dynamic-authentication.mdx | 2 +- fern/products/sdks/generators/python/configuration.mdx | 2 +- fern/products/sdks/generators/python/dynamic-authentication.mdx | 2 +- fern/products/sdks/generators/typescript/configuration.mdx | 2 +- .../sdks/generators/typescript/dynamic-authentication.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/fern/products/sdks/deep-dives/dynamic-authentication.mdx b/fern/products/sdks/deep-dives/dynamic-authentication.mdx index b4a4c45c43..9ffc30deba 100644 --- a/fern/products/sdks/deep-dives/dynamic-authentication.mdx +++ b/fern/products/sdks/deep-dives/dynamic-authentication.mdx @@ -37,7 +37,7 @@ When implementing dynamic authentication, keep these language-agnostic considera - **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 +- **Avoid double authentication**: If your API already uses bearer token authentication in the Fern definition, be careful not to override existing authentication headers. When the client never uses the credential it requires, make it optional in your [Python](/sdks/generators/python/configuration#optional_auth) or [TypeScript](/sdks/generators/typescript/configuration#optional-auth) generator configuration ### Performance diff --git a/fern/products/sdks/generators/python/configuration.mdx b/fern/products/sdks/generators/python/configuration.mdx index ccc756f843..bc8ca458ef 100644 --- a/fern/products/sdks/generators/python/configuration.mdx +++ b/fern/products/sdks/generators/python/configuration.mdx @@ -185,7 +185,7 @@ When enabled, the generated SDK sends a single structured `User-Agent` header of -When enabled, client auth parameters (bearer token, basic auth username and password, header auth) remain optional even when the API spec mandates auth on every endpoint, and requests are sent without an auth header when no credential is provided. By default, the client raises an error when a mandatory credential is missing. Also accepted as `optional-auth` or `optionalAuth`. +When enabled, client auth parameters (bearer token, basic auth username and password, header auth) remain optional even when the spec's [security requirements](/learn/api-definitions/openapi/authentication) mandate auth on every endpoint, and requests are sent without an auth header when no credential is provided. By default, the client raises an error when a mandatory credential is missing. Also accepted as `optional-auth` or `optionalAuth`. Enable this when callers authenticate through a mechanism other than the API's own scheme, such as cloud provider credentials, and would otherwise have to pass a placeholder value. diff --git a/fern/products/sdks/generators/python/dynamic-authentication.mdx b/fern/products/sdks/generators/python/dynamic-authentication.mdx index b821705192..7755151d3a 100644 --- a/fern/products/sdks/generators/python/dynamic-authentication.mdx +++ b/fern/products/sdks/generators/python/dynamic-authentication.mdx @@ -118,7 +118,7 @@ This same pattern works for other dynamic authentication scenarios: ### Security considerations - **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 +- **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, conditionally setting the header, or enabling [`optional_auth`](/sdks/generators/python/configuration#optional_auth) so the generated client doesn't require a credential it won't use ### Performance diff --git a/fern/products/sdks/generators/typescript/configuration.mdx b/fern/products/sdks/generators/typescript/configuration.mdx index 7dabcfd1ce..1627630dae 100644 --- a/fern/products/sdks/generators/typescript/configuration.mdx +++ b/fern/products/sdks/generators/typescript/configuration.mdx @@ -410,7 +410,7 @@ When enabled, the generated SDK sends a single structured `User-Agent` header of -When enabled, client auth parameters (bearer token, basic auth credentials, header auth) remain optional even when the API spec mandates auth on every endpoint, and requests are sent without an auth header when no credential is provided. By default, the client throws when a mandatory credential is missing. +When enabled, client auth parameters (bearer token, basic auth credentials, header auth) remain optional even when the spec's [security requirements](/learn/api-definitions/openapi/authentication) mandate auth on every endpoint, and requests are sent without an auth header when no credential is provided. By default, the client throws when a mandatory credential is missing. Enable this when callers authenticate through a mechanism other than the API's own scheme, such as cloud provider credentials, and would otherwise have to pass a placeholder value. diff --git a/fern/products/sdks/generators/typescript/dynamic-authentication.mdx b/fern/products/sdks/generators/typescript/dynamic-authentication.mdx index 3e43eec295..acb14c012d 100644 --- a/fern/products/sdks/generators/typescript/dynamic-authentication.mdx +++ b/fern/products/sdks/generators/typescript/dynamic-authentication.mdx @@ -177,7 +177,7 @@ This same pattern works for other dynamic authentication scenarios: - **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 +- **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, conditionally setting the header, or enabling [`optional-auth`](/sdks/generators/typescript/configuration#optional-auth) so the generated client doesn't require a credential it won't use ### Performance and concurrency From 6ad361a0a81505c1902fe0c890c26ba67242f24d Mon Sep 17 00:00:00 2001 From: William Kendall <43126467+willkendall01@users.noreply.github.com> Date: Fri, 31 Jul 2026 14:20:05 -0400 Subject: [PATCH 3/7] Simplify double authentication guidance in docs Removed redundant mention of optional authentication in the dynamic authentication documentation. --- fern/products/sdks/deep-dives/dynamic-authentication.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/deep-dives/dynamic-authentication.mdx b/fern/products/sdks/deep-dives/dynamic-authentication.mdx index 9ffc30deba..d78fad583b 100644 --- a/fern/products/sdks/deep-dives/dynamic-authentication.mdx +++ b/fern/products/sdks/deep-dives/dynamic-authentication.mdx @@ -37,7 +37,7 @@ When implementing dynamic authentication, keep these language-agnostic considera - **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. When the client never uses the credential it requires, make it optional in your [Python](/sdks/generators/python/configuration#optional_auth) or [TypeScript](/sdks/generators/typescript/configuration#optional-auth) generator configuration +- **Avoid double authentication**: If your API already uses bearer token authentication in the Fern definition, be careful not to override existing authentication headers. ### Performance From dded15d7073f50fb01265aff3fc7351abae0dfc4 Mon Sep 17 00:00:00 2001 From: William Kendall <43126467+willkendall01@users.noreply.github.com> Date: Fri, 31 Jul 2026 14:20:31 -0400 Subject: [PATCH 4/7] Update dynamic-authentication.mdx --- fern/products/sdks/deep-dives/dynamic-authentication.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/deep-dives/dynamic-authentication.mdx b/fern/products/sdks/deep-dives/dynamic-authentication.mdx index d78fad583b..b4a4c45c43 100644 --- a/fern/products/sdks/deep-dives/dynamic-authentication.mdx +++ b/fern/products/sdks/deep-dives/dynamic-authentication.mdx @@ -37,7 +37,7 @@ When implementing dynamic authentication, keep these language-agnostic considera - **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. +- **Avoid double authentication**: If your API already uses bearer token authentication in the Fern definition, be careful not to override existing authentication headers ### Performance From 494c1830192cc686104c3141bac47aefd21934d7 Mon Sep 17 00:00:00 2001 From: William Kendall <43126467+willkendall01@users.noreply.github.com> Date: Fri, 31 Jul 2026 14:21:13 -0400 Subject: [PATCH 5/7] Update security considerations in dynamic-authentication.mdx Clarified security considerations regarding double authentication and header management. --- .../sdks/generators/typescript/dynamic-authentication.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/generators/typescript/dynamic-authentication.mdx b/fern/products/sdks/generators/typescript/dynamic-authentication.mdx index acb14c012d..3e43eec295 100644 --- a/fern/products/sdks/generators/typescript/dynamic-authentication.mdx +++ b/fern/products/sdks/generators/typescript/dynamic-authentication.mdx @@ -177,7 +177,7 @@ This same pattern works for other dynamic authentication scenarios: - **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, conditionally setting the header, or enabling [`optional-auth`](/sdks/generators/typescript/configuration#optional-auth) so the generated client doesn't require a credential it won't use +- **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 From 45d35405d841055e6d29a931b26e908651f7dcd0 Mon Sep 17 00:00:00 2001 From: William Kendall <43126467+willkendall01@users.noreply.github.com> Date: Fri, 31 Jul 2026 14:21:41 -0400 Subject: [PATCH 6/7] Simplify security considerations for authentication Removed redundant advice on avoiding double authentication in security considerations. --- .../products/sdks/generators/python/dynamic-authentication.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/fern/products/sdks/generators/python/dynamic-authentication.mdx b/fern/products/sdks/generators/python/dynamic-authentication.mdx index 7755151d3a..dac110b446 100644 --- a/fern/products/sdks/generators/python/dynamic-authentication.mdx +++ b/fern/products/sdks/generators/python/dynamic-authentication.mdx @@ -118,8 +118,7 @@ This same pattern works for other dynamic authentication scenarios: ### Security considerations - **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, conditionally setting the header, or enabling [`optional_auth`](/sdks/generators/python/configuration#optional_auth) so the generated client doesn't require a credential it won't use - +- **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 - **Token memoization**: Consider caching tokens to avoid regenerating them on every request. You can add a simple cache that refreshes tokens before they expire From afa5b99751e37b400977acc0a303feed8a27f772 Mon Sep 17 00:00:00 2001 From: William Kendall <43126467+willkendall01@users.noreply.github.com> Date: Fri, 31 Jul 2026 14:22:14 -0400 Subject: [PATCH 7/7] Enhance documentation with performance tips Added performance considerations for token management. --- fern/products/sdks/generators/python/dynamic-authentication.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/fern/products/sdks/generators/python/dynamic-authentication.mdx b/fern/products/sdks/generators/python/dynamic-authentication.mdx index dac110b446..b821705192 100644 --- a/fern/products/sdks/generators/python/dynamic-authentication.mdx +++ b/fern/products/sdks/generators/python/dynamic-authentication.mdx @@ -119,6 +119,7 @@ This same pattern works for other dynamic authentication scenarios: - **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 + ### Performance - **Token memoization**: Consider caching tokens to avoid regenerating them on every request. You can add a simple cache that refreshes tokens before they expire