Skip to content

docs: document opt-in appInfo User-Agent option for TypeScript and Python SDKs #6498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
devin-ai-integration wants to merge 1 commit into
base: main
Choose a base branch
from
+38 −0
Open

docs: document opt-in appInfo User-Agent option for TypeScript and Python SDKs #6498

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions fern/products/sdks/generators/python/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,25 @@ 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.
</ParamField>

<ParamField path="allow_user_agent_app_info" type="bool" default="false" required={false} toc={true}>
When enabled, the generated client constructor accepts `app_info: typing.Optional[typing.Dict[str, str]] = None`, with a required `name` key and optional `version` and `comment` keys. Its product token is appended to the `User-Agent` header, which lets an application built on the SDK identify itself to the API, following the [HTTP `User-Agent` grammar](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent). Also accepted as `allowUserAgentAppInfo`.

```python
client = Acme(
token="...",
app_info={"name": "partner-app", "version": "3.1.0", "comment": "+https://partner.example"},
)
```

The token is formatted as `{name}/{version} ({comment})`, dropping `/{version}` and `({comment})` when blank, and is appended to whatever `User-Agent` the SDK would otherwise send, including the structured header from [`include_platform_headers`](#include_platform_headers) and the version resolved by [`runtime_version`](#runtime_version):

```
User-Agent: fern_examples/0.0.1 (linux; x86_64) Python/3.11.0 partner-app/3.1.0 (+https://partner.example)
```

Caller-supplied values are sanitized before they reach the header. An explicit `User-Agent` header takes precedence, the header is unchanged when no `name` is passed, and [`omit_fern_headers`](#omit_fern_headers) suppresses it entirely.
</ParamField>

<ParamField path="optional_auth" type="bool" default="false" required={false} toc={true}>
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`.

Expand Down
19 changes: 19 additions & 0 deletions fern/products/sdks/generators/typescript/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -409,6 +409,25 @@ 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.
</ParamField>

<ParamField path="allowUserAgentAppInfo" type="boolean" default="false" toc={true}>
When enabled, the generated client accepts an optional `appInfo` client option with a required `name` and optional `version` and `comment`. Its product token is appended to the `User-Agent` header, which lets an application built on the SDK identify itself to the API, following the [HTTP `User-Agent` grammar](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent).

```typescript
const client = new AcmeClient({
token: "...",
appInfo: { name: "partner-app", version: "3.1.0", comment: "+https://partner.example" },
});
```

The token is formatted as `{name}/{version} ({comment})`, dropping `/{version}` and `({comment})` when blank, and is appended to whatever `User-Agent` the SDK would otherwise send, including the structured header from [`includePlatformHeaders`](#includePlatformHeaders):

```
User-Agent: @fern/simple-api/0.0.1 (linux; x86_64) Node/22.x partner-app/3.1.0 (+https://partner.example)
```

Caller-supplied values are sanitized before they reach the header. A `User-Agent` set explicitly in client or request headers takes precedence, and the header is unchanged when no `appInfo` is passed.
</ParamField>

<ParamField path="optional-auth" type="boolean" default="false" toc={true}>
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.

Expand Down
Loading