diff --git a/fern/products/api-def/ferndef/api-yml/global-configuration.mdx b/fern/products/api-def/ferndef/api-yml/global-configuration.mdx
index 7d1c1bbef1..cf081661e7 100644
--- a/fern/products/api-def/ferndef/api-yml/global-configuration.mdx
+++ b/fern/products/api-def/ferndef/api-yml/global-configuration.mdx
@@ -23,6 +23,22 @@ headers:
When you define global headers in your `api.yml`, you must [include them in your endpoint examples](/api-definitions/ferndef/examples#examples-with-headers).
+The object form of a header accepts `env`, an environment variable the generated SDK reads, and `client-default`, the value the SDK sends when nothing else supplies one:
+
+
+```yaml
+name: api
+headers:
+ X-API-Version:
+ name: version
+ type: optional
+ env: MY_API_VERSION
+ client-default: "2024-01-01"
+```
+
+
+Generated SDKs resolve the header value from an explicit argument passed to the client constructor or a single request, then `env`, then `client-default`. The same keys are available for headers declared in [`generators.yml`](/learn/sdks/reference/generators-yml#headers).
+
## Global path parameters
You can specify path parameters that are meant to be included on every request:
diff --git a/fern/products/api-def/openapi/extensions/global-headers.mdx b/fern/products/api-def/openapi/extensions/global-headers.mdx
index d684a1b423..9604c6939d 100644
--- a/fern/products/api-def/openapi/extensions/global-headers.mdx
+++ b/fern/products/api-def/openapi/extensions/global-headers.mdx
@@ -50,16 +50,19 @@ Alternatively, you can add headers to the [`api` block in your `generators.yml`
```yaml title="generators.yml"
api:
- - openapi: ./path/to/openapi
- headers:
- custom_api_key:
- name: api_key
- type: string
- userpool_id:
- name: userpool_id
- type: optional
+ specs:
+ - openapi: ./path/to/openapi
+ headers:
+ custom_api_key:
+ name: api_key
+ type: string
+ userpool_id:
+ name: userpool_id
+ type: optional
```
+A header declared in `generators.yml` also accepts `env` (an environment variable the SDK reads) and `client-default` (the value the SDK sends when nothing else supplies one). Generated SDKs resolve the value from an explicit argument first, then `env`, then `client-default`. For the full set of keys, see [`api.headers`](/learn/sdks/reference/generators-yml#headers).
+
## Generated SDK behavior
Both configurations yield the following client code:
diff --git a/fern/products/sdks/deep-dives/configure-global-headers.mdx b/fern/products/sdks/deep-dives/configure-global-headers.mdx
index 173a952638..4b1a67f2af 100644
--- a/fern/products/sdks/deep-dives/configure-global-headers.mdx
+++ b/fern/products/sdks/deep-dives/configure-global-headers.mdx
@@ -34,4 +34,18 @@ x-fern-global-headers:
You can also pin a [default value](/learn/api-definitions/openapi/extensions/default-values) on a global header so the SDK sends it automatically when the caller doesn't provide one.
+Headers declared in [`generators.yml`](/learn/sdks/reference/generators-yml#headers) or in a Fern Definition [`api.yml`](/learn/api-definitions/ferndef/api-yml/global-headers) additionally accept `env` and `client-default`:
+
+```yaml title="generators.yml"
+api:
+ headers:
+ X-API-Version:
+ name: version
+ type: optional
+ env: MY_API_VERSION
+ client-default: "2024-01-01"
+```
+
+Every SDK language resolves the value in the same order: an option set on a single request, then the value passed to the client constructor, then the `MY_API_VERSION` environment variable, then `2024-01-01`. A value passed to the constructor persists across every request the client makes; per-request options override it only when the caller sets them.
+
For full configuration details, see [Global headers in OpenAPI](/learn/api-definitions/openapi/extensions/global-headers).
diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx
index 1539547a49..20fe21172d 100644
--- a/fern/products/sdks/reference/generators-yml-reference.mdx
+++ b/fern/products/sdks/reference/generators-yml-reference.mdx
@@ -208,6 +208,14 @@ api:
Global headers to include with all API requests. This is an alternative to configuring [global headers in your OpenAPI spec](/learn/api-definitions/openapi/extensions/global-headers). You can specify headers as simple string values or as objects with additional configuration for code generation.
+ The object form supports these keys:
+
+ - `name`: the parameter name used in generated SDK code. Defaults to the header name.
+ - `type`: the header type for code generation, such as `string`, `optional`, or `literal<"1234">`.
+ - `env`: the environment variable the generated SDK reads when the caller doesn't supply the header.
+ - `client-default`: the value the generated SDK sends when neither an explicit value nor `env` supplies one.
+ - `default`: a documentation-only value displayed in the API Reference. It has no effect on generated SDKs.
+
@@ -222,18 +230,19 @@ api:
```yaml title="generators.yml"
api:
- - openapi: ./path/to/openapi
- headers:
- X-Version:
- # The variable name to use in generated SDK code.
- # If not specified, uses the header name.
- name: version
- # The type of the header value for code generation
- # (e.g., "string", "literal<'value'>", "number").
- type: literal<"1234">
+ specs:
+ - openapi: ./path/to/openapi
+ headers:
+ X-API-Version:
+ name: version
+ type: optional
+ env: MY_API_VERSION
+ client-default: "2024-01-01"
```
+
+ Generated SDKs resolve a [global header](/learn/sdks/deep-dives/global-headers) value in a fixed order: an option set on a single request, then the value passed to the client constructor, then the `env` environment variable, then `client-default`. The order is identical in TypeScript, Java, Python, Go, C#, Ruby, and PHP.