> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# generators.yml configuration schema

> Complete generators.yml configuration reference for Fern SDK generation. Configure authentication, publishing, GitHub integration, and language-specific settings.

The `generators.yml` file serves two purposes: it declares your API definition (required for OpenAPI/AsyncAPI), and configures SDK generation, including which languages to generate, where to publish them, and how to customize each SDK.

A `# yaml-language-server` directive at the top of `generators.yml` enables validation and autocompletion in editors that use the [YAML Language Server](https://github.com/redhat-developer/yaml-language-server), such as VS Code with the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml), Neovim, and Emacs. IntelliJ ignores the directive; map `https://schema.buildwithfern.dev/generators-yml.json` to `generators.yml` under **Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings** instead.

**`generators.yml`**

```yaml title="generators.yml" maxLines=10
# yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json
api:
  specs:
    - openapi: "./openapi.yml"
      namespace: "v1"
      settings:
        title-as-schema-name: true
        inline-path-parameters: false
        respect-forward-compatible-enums: true

whitelabel:
  github:
    username: "my-org"
    email: "sdk@mycompany.com"
    token: "ghp_xxxxxxxxxxxx"

metadata:
  description: "Official SDK for MyAPI"
  authors:
    - name: "SDK Team"
      email: "sdk@mycompany.com"

readme:
  introduction: "Welcome to the MyAPI SDK"
  apiReferenceLink: "https://docs.myapi.com"
  defaultEndpoint:
    method: "GET"
    path: "/users"
  features:
    authentication:
      - "POST /auth/login"
      - "GET /auth/profile"
    users:
      - "GET /users"
      - "POST /users"

default-group: "production"

groups:
  production:
    generators:
      - name: fern-typescript-sdk
        version: 0.9.0
      - name: fern-python-sdk
        version: 2.0.0
```

## `auth-schemes`

Define authentication methods for your SDKs and the [API Explorer](/learn/docs/api-references/api-explorer) that your endpoints can reference. Authentication schemes defined in `generators.yml` take precedence over authentication schemes [defined in your spec](/learn/api-definitions/openapi/authentication).

After defining an authentication scheme, you must use [`api.auth`](#auth) to apply it as the default across all endpoints. Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings) if you need different auth behavior per language.

**`generators.yml`**

```yaml title="generators.yml" maxLines=10
auth-schemes:
  # User-defined scheme name - OAuth with minimal configuration
  simple-oauth:
    scheme: oauth
    type: client-credentials
    get-token:
      endpoint: "auth.token"
    
  # User-defined scheme name - Header auth with custom configuration
  custom-header:
    name: "Custom Auth"
    header: "X-Custom-Auth"
    prefix: "Custom "
    env: "CUSTOM_TOKEN"
    
  # User-defined scheme name - Basic auth
  http-basic:
    scheme: basic
    
  # User-defined scheme name - Bearer token
  jwt-bearer:
    scheme: bearer
```

Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication:

#### Header

Configure authentication using custom HTTP headers, such as API keys or tokens.

```yaml
auth-schemes:
  api-key: # User-defined scheme name
    name: "API Key Authentication"
    header: "X-API-Key"
    type: "string"
    prefix: "ApiKey "
    env: "MY_API_KEY" # SDK will auto-scan this environment variable
```

**`header`** `string` — required

The name of the HTTP header to use for authentication.

---

**`name`** `string`

A descriptive name for this authentication scheme.

---

**`type`** `string` — default: string

The type of the header value.

---

**`prefix`** `string`

A prefix to prepend to the header value (e.g., `"Bearer "` or `"Token "`).

---

**`env`** `string`

Environment variable name containing the authentication value. When specified, the generated SDK will automatically scan for this environment variable at initialization.

---

#### Basic

Configure HTTP Basic authentication using username and password credentials.

```yaml
auth-schemes:
  basic-auth: # User-defined scheme name
    scheme: basic
    username:
      name: "Username"
      env: "BASIC_AUTH_USERNAME" # SDK will auto-scan this environment variable
    password:
      name: "Password"
      env: "BASIC_AUTH_PASSWORD" # SDK will auto-scan this environment variable
```

**`scheme`** `'basic'` — required

Must be set to `"basic"` for Basic authentication schemes.

---

**`username`** `object`

Configuration for the username credential.

---

**`username.name`** `string`

Custom parameter name for the username in the generated SDK. If not specified, defaults to `"username"`. Use this to provide more descriptive or domain-specific parameter names like `"clientId"`, `"userEmail"`, or `"merchantId"`.

---

**`password`** `object`

Configuration for the password credential.

---

**`password.name`** `string`

Custom parameter name for the password in the generated SDK. If not specified, defaults to `"password"`. Use this to provide more descriptive or domain-specific parameter names like `"clientSecret"`, `"apiKey"`, or `"merchantKey"`.

---

**`username.env, password.env`** `string`

Environment variable name that the SDK will automatically scan for the username or password value. When this environment variable is present, users don't need to explicitly provide the username parameter. Follow naming conventions like `YOUR_APP_USERNAME` or `SERVICE_CLIENT_ID`.

---

**`username.omit, password.omit`** `boolean` — default: false

Use when your API expects only one half of the basic auth credential pair. When `true`, the field is removed from the generated SDK's public API. The omitted field is treated as an empty string when encoding the `Authorization` header (omitting `password` produces `base64("username:")`; omitting `username` produces `base64(":password")`). When both are omitted, the `Authorization` header is skipped entirely.

---

#### Bearer token

Configure Bearer token authentication for API access.

```yaml
auth-schemes:
  bearer-token: # User-defined scheme name
    scheme: bearer
    token:
      name: "Access Token"
      env: "BEARER_TOKEN" # SDK will auto-scan this environment variable
```

**`scheme`** `'bearer'` — required

Must be set to `"bearer"` for Bearer token authentication schemes.

---

**`token`** `object`

Configuration for the bearer token.

---

**`token.name`** `string`

A descriptive name for the token.

---

**`token.env`** `string`

Environment variable name containing the bearer token. When specified, the generated SDK will automatically scan for this environment variable at initialization.

---

#### OAuth client credentials

For OpenAPI, [OAuth must be configured in `generators.yml`](/learn/api-definitions/openapi/authentication#oauth-client-credentials).

Configure OAuth 2.0 client credentials authentication. Optionally configure a `refresh-token` endpoint for token renewal without re-authentication.

**`generators.yml`**

```yaml title="generators.yml" maxLines=10
auth-schemes:
  my-oauth: # User-defined scheme name
    scheme: oauth
    type: client-credentials
    scopes:
      - "read:users"
      - "write:users"
    client-id-env: "OAUTH_CLIENT_ID" # SDK will auto-scan this environment variable
    client-secret-env: "OAUTH_CLIENT_SECRET" # SDK will auto-scan this environment variable
    token-prefix: "Bearer"
    token-header: "Authorization"
    get-token:
      endpoint: "auth.get_token"
      request-properties:
        client-id: "clientId"
        client-secret: "clientSecret"
        scopes: "scope"
      response-properties:
        access-token: "access_token"
        expires-in: "expires_in"
        refresh-token: "refresh_token"
    refresh-token:
      endpoint: "auth.refresh_token"
      request-properties:
        refresh-token: "refreshToken"
      response-properties:
        access-token: "access_token"
        expires-in: "expires_in"
        refresh-token: "refresh_token"
```

**`scheme`** `'oauth'` — required

Must be set to `"oauth"` for OAuth authentication schemes.

---

**`type`** `'client-credentials'` — required

The OAuth 2.0 grant type. Currently only `"client-credentials"` is supported.

---

**`scopes`** `list of strings`

OAuth scopes to request when obtaining access tokens (e.g., `"read:users"`, `"write:orders"`).

---

**`client-id-env`** `string`

Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization.

---

**`client-secret-env`** `string`

Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization.

---

**`token-prefix`** `string` — default: Bearer

Prefix added to the access token in the Authorization header (e.g., `"Bearer"` results in `"Authorization: Bearer <token>"`). Useful when your API expects a custom format.

---

**`token-header`** `string` — default: Authorization

HTTP header name used to send the access token. Defaults to `"Authorization"` but can be customized if your API uses a different header (e.g., `"X-API-Token"`).

---

#### `get-token`

Specifies the endpoint that exchanges client credentials for an access token. This endpoint is called automatically when the SDK client is initialized.

**`generators.yml`**

```yaml title="generators.yml"
get-token:
  endpoint: "auth.get_token"
  request-properties:
    client-id: "clientId"
    client-secret: "clientSecret"
  response-properties:
    access-token: "access_token"
    expires-in: "expires_in"
```

**`endpoint`** `string` — required

The endpoint that issues access tokens, such as `'auth.get_token'` or `'POST /oauth/token'`. If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `'payments::POST /oauth/token'`).

---

**`request-properties`** `object`

Maps OAuth parameter names to your API's request field names. Use this when your token endpoint expects different field names than the OAuth standard (e.g., your API uses `clientId` instead of `client_id`).

---

**`request-properties.client-id`** `string`

The request field name for the client ID in your API (e.g., `"clientId"`, `"client_id"`).

---

**`request-properties.client-secret`** `string`

The request field name for the client secret in your API (e.g., `"clientSecret"`, `"client_secret"`).

---

**`request-properties.scopes`** `string`

The request field name for scopes in your API (e.g., `"scope"`, `"scopes"`).

---

**`response-properties`** `object`

Maps your API's response field names to OAuth standard names. Use this when your API returns tokens with different field names (e.g., `accessToken` instead of `access_token`).

---

**`response-properties.access-token`** `string`

The response field name for the access token in your API (e.g., `"accessToken"`, `"access_token"`).

---

**`response-properties.expires-in`** `string`

The response field name for token expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). When present, the SDK automatically refreshes tokens before expiration.

---

**`refresh-token`** `string`

The response field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`). Required if using the `refresh-token` flow.

---

#### `refresh-token`

Specifies the endpoint that exchanges a refresh token for a new access token. When configured, the SDK automatically uses this endpoint to renew expired tokens without re-sending credentials. If not configured, the SDK will re-authenticate using `get-token` when tokens expire.

**`generators.yml`**

```yaml title="generators.yml"
refresh-token:
  endpoint: "auth.refresh_token"
  request-properties:
    refresh-token: "refreshToken"
  response-properties:
    access-token: "access_token"
    expires-in: "expires_in"
```

**`endpoint`** `string` — required

The endpoint that refreshes access tokens (e.g., `"POST /oauth/refresh"` or `"auth.refreshToken"`). If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `"payments::POST /oauth/refresh"`).

---

**`request-properties`** `object`

Maps OAuth parameter names to your API's request field names for the refresh flow.

---

**`request-properties.refresh-token`** `string` — required

The request field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`).

---

**`response-properties`** `object`

Maps your API's refresh response field names to OAuth standard names.

---

**`response-properties.access-token`** `string`

The response field name for the new access token (e.g., `"accessToken"`, `"access_token"`).

---

**`response-properties.expires-in`** `string`

The response field name for the new token's expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`).

---

**`response-properties.refresh-token`** `string`

The response field name if your API issues a new refresh token with each refresh (token rotation).

---

## `api`

Defines the API specification (OpenAPI, AsyncAPI, etc.) and how to parse it.

**`generators.yml`**

```yaml title="generators.yml" maxLines=10
api:
  settings:
    inline-path-parameters: true # Applies to all OpenAPI specs
  specs:
    - openapi: "./openapi.yml"
      namespace: "v1"
      settings:
        title-as-schema-name: true # Applies only to this OpenAPI spec
    - asyncapi: "./events.yml"
      namespace: "events"
  headers:
    Authorization: "Bearer ${API_TOKEN}"
  environments:
    production: "https://api.prod.com"
    staging: "https://api.staging.com"
```

**`auth`** `string | object`

Sets the default authentication scheme for all endpoints. Scheme names must reference entries defined in [`auth-schemes`](#auth-schemes). This overrides any security schemes [defined in your OpenAPI spec](/learn/api-definitions/openapi/authentication).

Pass a string for a single scheme, or an object with `any` or `all` to compose multiple schemes. Pass the string `endpoint-security` to route auth per endpoint instead of applying one default scheme everywhere.

#### Single scheme

**`generators.yml`**

```yaml title="generators.yml"
api:
  auth: BearerAuth
  specs:
    - openapi: ./openapi.yml
```

#### Multiple schemes (any)

Accept any one of several schemes. The first scheme with a credential wins.

**`generators.yml`**

```yaml title="generators.yml"
auth-schemes:
  BearerAuth:
    scheme: bearer
    token:
      name: apiKey
      env: MY_API_KEY
  TokenAuth:
    scheme: bearer
    token:
      name: token
      env: MY_TOKEN

api:
  auth:
    any:
      - BearerAuth
      - TokenAuth
  specs:
    - openapi: ./openapi.yml
      overrides: ./openapi-overrides.yml
```

Both schemes must also be declared in the OpenAPI spec's [`securitySchemes` and `security` array](/learn/api-definitions/openapi/authentication#multiple-auth-schemes). A scheme that's missing from the spec is silently ignored, even when its credential is set.

#### Multiple schemes (all)

Require every scheme simultaneously (for example, HMAC signature plus API key).

**`generators.yml`**

```yaml title="generators.yml"
api:
  auth:
    all:
      - HmacAuth
      - ApiKeyAuth
  specs:
    - openapi: ./openapi.yml
```

#### Per-endpoint routing (endpoint-security)

Instead of applying one default scheme to every endpoint, `endpoint-security` routes auth per endpoint using each operation's declared `security`: `OR` across the requirement list, `AND` within a single requirement. An operation with `security: []` sends no credentials, and an operation with no satisfiable requirement raises an error naming the missing scheme(s). This is supported across all SDK languages.

**`generators.yml`**

```yaml title="generators.yml"
api:
  auth: endpoint-security
  specs:
    - openapi: ./openapi.yml
```

For example, if `POST /plants/{plantId}` declares OAuth Bearer `OR` an API key header, the SDK sends whichever credential is set; a token endpoint with `security: []` is called anonymously.

You can also override authentication for individual generators using the [generator-level `api.auth`](#override-api-authentication-settings) setting.

---

**`headers`** `string or list of objects`

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<string>`, 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. This is the equivalent of [`x-fern-default`](/learn/api-definitions/openapi/extensions/default-values) on an OpenAPI global header.
* `default`: a documentation-only value displayed in the API Reference. It has no effect on generated SDKs.

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`.

#### Simple string values

**`generators.yml`**

```yaml title="generators.yml"
api:
  headers:
    Authorization: "Bearer ${API_TOKEN}"
    X-App-Version: "1.0.0"
```

#### Object configuration

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - openapi: ./path/to/openapi
  headers:
    X-API-Version:
      name: version
      type: optional<string>
      env: MY_API_VERSION
      client-default: "2024-01-01"
```

---

**`environments`** `object`

Environment configurations for different deployment targets.

---

**`settings`** `object`

Settings that apply to all specs of a given type (e.g., all OpenAPI specs). Can be overridden at the spec or generator level. Precedence: generator-level settings override spec-level settings, which override global settings.

For example, use this to ensure consistent parsing behavior across all your OpenAPI specs. For available settings, see the [specification type](#specification-types) documentation below.

---

**`settings.auto-generate-idempotency-key`** `boolean | object` — default: false

Enables [idempotency-key auto-generation](/learn/sdks/deep-dives/idempotency#auto-generate-idempotency-keys) for every generator in the API, instead of setting it under each generator's `config`. When enabled, generated SDKs attach a UUIDv4 idempotency-key header on eligible methods unless the caller supplies one.

Pass `true` for the defaults, or an object to set `header-name` (default `Idempotency-Key`) and `methods` (default `["POST", "PUT"]`). A generator's own `config.auto-generate-idempotency-key` overrides this value, including an explicit `false` to opt out.

**`generators.yml`**

```yaml title="generators.yml"
api:
  settings:
    auto-generate-idempotency-key: true
```

Or pass an object to customize the header and methods:

**`generators.yml`**

```yaml title="generators.yml"
api:
  settings:
    auto-generate-idempotency-key:
      header-name: X-Idempotency-Key
      methods:
        - POST
        - PUT
        - PATCH
```

---

### Specification types

Each specification type (OpenAPI, AsyncAPI, etc.) supports various configuration options including the spec file location, namespace, overrides, and type-specific settings.

#### OpenAPI

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - openapi: "./openapi.yml"
      origin: "https://api.example.com/openapi.json"
      overlays: "./openapi-overlays.yml"
      overrides: "./openapi-overrides.yml" # or a list of paths
      namespace: "v1"
      settings:
        title-as-schema-name: true
        ignore-tags: true
        inline-path-parameters: false
        inline-all-of-schemas: true
        prefer-undiscriminated-unions-with-literals: true
        respect-parameter-content: true
        filter:
          endpoints: ["POST /users", "GET /users/{id}"]
        example-generation:
          request:
            max-depth: 2
    - openapi:
        git:
          repo: https://github.com/org/private-api-specs.git
          ref: main
          path: openapi/service-a.yml
      overrides: ./local-overrides.yml
```

**`openapi`** `string | git` — required

Location of the OpenAPI specification file. Accepts a local file path or a remote git reference.

```yaml
# Local file
openapi: ./openapi.yml

# Remote git repository
openapi:
  git:
    repo: https://github.com/org/api-specs.git
    ref: main
    path: openapi/service.yml
```

---

**`openapi.git.repo`** `string` — required

The git repository URL (e.g., `https://github.com/org/repo.git`). The CLI shallow-clones this repository at generation time using your system's git credential configuration (credential helpers, SSH keys, `GIT_ASKPASS`).

---

**`openapi.git.ref`** `string`

Branch, tag, or commit SHA to check out. Defaults to the repository's default branch when omitted.

---

**`openapi.git.path`** `string` — required

Path to the spec file within the repository.

---

**`origin`** `string`

URL of the API definition origin for pulling updates. For instructions on how to set up automatic syncing, refer to [Sync your OpenAPI specification](/learn/api-definitions/openapi/sync-your-open-api-specification).

---

**`overlays`** `string`

Path to an [OpenAPI Overlay](/learn/api-definitions/openapi/overlays) file. Overlays follow the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) and are the recommended approach for customizing OpenAPI specifications.

---

**`overrides`** `string | list of strings`

Path to an OpenAPI [overrides](/learn/api-definitions/openapi/overrides) file, or a list of paths to multiple override files applied sequentially. Consider using `overlays` instead for a standards-based approach.

```yaml
# Single override file
overrides: ./overrides.yml

# Multiple override files (applied in order)
overrides:
  - ./base-overrides.yml
  - ./sdk-overrides.yml
```

---

**`namespace`** `string`

Namespace for the specification. Useful for configuring a [single package with multiple API versions](/learn/api-definitions/overview/project-structure#option-2-namespace-based-versioning).

---

**`settings`** `object`

OpenAPI-specific generation settings for this individual spec. To apply the same settings across all OpenAPI specs, use global [`api.settings`](/learn/sdks/reference/generators-yml#settings) instead.

---

**`settings.title-as-schema-name`** `boolean` — default: false

Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern.

---

**`settings.inline-path-parameters`** `boolean` — default: true

Whether to include path parameters within the generated in-lined request.

---

**`settings.inline-all-of-schemas`** `boolean` — default: false

Whether to inline `allOf` schemas during code generation. When true, Fern recursively visits `allOf` schema definitions and inlines them into the child schema. When false, `allOf` schemas are extended through inheritance.

Enabling this setting allows child schemas to override parent property requirements. For example, a child schema can mark a parent's required property as optional. Without this setting, Fern ignores the child schema's optional declaration and preserves the parent schema's requirement instead.

---

**`settings.prefer-undiscriminated-unions-with-literals`** `boolean` — default: false

Whether to prefer undiscriminated unions with literals.

---

**`settings.only-include-referenced-schemas`** `boolean` — default: false

Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking).

---

**`settings.respect-nullable-schemas`** `boolean` — default: true

Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.

---

**`settings.object-query-parameters`** `boolean` — default: true

Enables parsing deep object query parameters.

---

**`settings.wrap-references-to-nullable-in-optional`** `boolean` — default: false

Controls whether references to nullable schemas are wrapped in optional types. When false, nullable references are treated as required fields that can be null.

---

**`settings.coerce-optional-schemas-to-nullable`** `boolean` — default: false

Controls whether optional schemas are coerced to nullable types during code generation. When false, optional and nullable are treated as distinct concepts.

---

**`settings.any-of-sibling-properties-as-object`** `boolean` — default: false

Converts a schema whose `anyOf` branches only mark sibling `properties` as `required` (an "at least one of" constraint) into a single object with optional fields instead of an undiscriminated union, so a request body that sets several of those properties keeps all of them instead of dropping all but one. Off by default because it changes generated types. Since every property is generated as optional, the SDK doesn't enforce that at least one is set; the API rejects a request that omits all of them.

---

**`settings.respect-readonly-schemas`** `boolean`

Enables exploring readonly schemas in OpenAPI specifications.

---

**`settings.respect-parameter-content`** `boolean` — default: false

Types a header parameter declared with a JSON `content` map from that schema instead of falling back to `string`, so SDKs get a typed object and the API Reference renders per-field inputs. Off by default because it changes generated SDK method signatures. Query parameters declared with `content` stay `string`.

---

**`settings.respect-forward-compatible-enums`** `boolean` — default: false

Enables respecting forward compatible enums in OpenAPI specifications.

---

**`settings.use-bytes-for-binary-response`** `boolean`

Enables using the `bytes` type for binary responses. Defaults to file stream.

---

**`settings.default-form-parameter-encoding`** `string` — default: json

The default encoding of form parameters. Options: `form`, `json`.

---

**`settings.additional-properties-defaults-to`** `boolean` — default: false

Configure what `additionalProperties` should default to when not explicitly defined on a schema.

---

**`settings.type-dates-as-strings`** `boolean` — default: false

If true, convert strings with format date to strings. If false, convert to dates.

---

**`settings.preserve-single-schema-oneof`** `boolean` — default: false

If true, preserve oneOf structures with a single schema. If false, unwrap them. For a `oneOf` nested inside an `allOf`, use [`preserve-one-of-in-all-of`](/learn/api-definitions/openapi/generators-yml-reference#settingspreserve-one-of-in-all-of).

---

**`settings.preserve-one-of-in-all-of`** `boolean` — default: false

Whether to keep a `oneOf` or `anyOf` that appears as a member of an `allOf` as a union. When `false`, every variant's properties are merged into a single object and marked optional, which makes invalid property combinations representable. When `true`, the `allOf` is distributed over the union: `allOf: [oneOf: [A, B, C], S]` becomes `oneOf: [A & S, B & S, C & S]`, an undiscriminated union in which each variant keeps its own required properties alongside the shared ones.

Enabling this setting changes the generated request and response shapes for affected schemas in every SDK, and the API Reference renders a variant selector for them. Union members that declare a [`discriminator`](/learn/api-definitions/openapi/extensions/discriminator-context) are left intact.

---

**`settings.filter`** `object`

Filter to apply to the OpenAPI specification. Use this to limit which endpoints are included in the generated SDK or API Reference docs [based on their paths](/learn/api-definitions/openapi/extensions/audiences#path-based-filtering).

For tag-based filtering instead of path-based filtering, use [`audiences`](/learn/sdks/reference/generators-yml#audiences) at the `group` level.

---

**`settings.filter.endpoints`** `list of strings`

Endpoints to include in the generated SDK. Specify endpoints in the format `METHOD /path` (e.g., `POST /users`, `GET /users/{id}`). Only the listed endpoints will be included in the generated SDK; all other endpoints will be excluded. If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `payments::POST /users`).

---

**`settings.example-generation.request.max-depth`** `integer`

Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples.

---

**`settings.example-generation.response.max-depth`** `integer`

Controls the maximum depth for which optional properties will have examples generated in responses.

---

**`settings.coerce-enums-to-literals`** `boolean` — default: false

Controls whether enums are converted to literal types during code generation. When `false` (default), enums are preserved as enum types, maintaining the original enum structure from your OpenAPI specification. When `true`, enums are coerced to literal types, which can be useful for simpler type representations in generated code.

---

**`settings.idiomatic-request-names`** `boolean` — default: true

Controls the naming convention for autogenerated request names. When enabled, places the verb before the noun in request names (e.g., `UsersListRequest` becomes `ListUsersRequest`), following more idiomatic naming patterns.

---

**`settings.ignore-tags`** `boolean` — default: false

Ignores operation-level OpenAPI `tags` when determining SDK structure. Endpoints fall back to the root package (or their `namespace`), and method names are derived from each operation's `operationId`. See [ignore tags](/learn/api-definitions/openapi/extensions/method-names#ignore-tags) for precedence rules and examples.

---

**`settings.resolve-aliases`** `boolean` — default: false

Inlines type aliases to simplify your generated SDK. When enabled, reduces
unnecessary type definitions by replacing simple aliases with their underlying
types directly. Useful for OpenAPI specs with many primitive or simple type
aliases.

Set to `true` to inline all aliases, or use an object with an `except` array
to preserve specific type aliases:

```yaml
settings:
  # Inline all aliases
  resolve-aliases: true

  # Or preserve specific aliases
  resolve-aliases:
    except:
      - UserId
      - OrganizationId
```

---

**`settings.respect-per-spec-base-path`** `boolean` — default: false

When merging multiple OpenAPI specs, applies each document's [`x-fern-base-path`](/learn/api-definitions/openapi/extensions/base-path) to its own endpoints only. When `false`, one document's base path is prepended to every endpoint across all specs. Parameterized base paths such as `/{tenant}/v1` stay at the API root, and differing parameterized base paths across documents raise a conflict.

If you worked around the dropped prefix by adding it to your [server URL](/learn/api-definitions/openapi/extensions/server-names) (for example, `https://api.example.com/api/v3`), remove it when enabling this setting. Otherwise the prefix is applied twice.

---

**`settings.group-environments-by-host`** `boolean` — default: false

When enabled, groups servers by host into unified environments, enabling APIs with multiple protocols (REST, WebSocket, etc.) to share environment configuration. Environment URL IDs use the server name, with path or protocol suffixes added only when needed to resolve collisions.

---

**`settings.namespaced-errors`** `boolean` — default: false

When enabled, shared error responses tagged with [`x-fern-sdk-namespace`](/learn/api-definitions/openapi/extensions/sdk-namespaces) in `components.responses` are generated as typed errors in that namespace (for example, `plants.TooManyRequestsError`) instead of being compared API-wide by status code. Applies only to the spec that sets it.

```yaml
settings:
  namespaced-errors: true
```

---

#### AsyncAPI

```yaml
api:
  specs:
    - asyncapi: "./asyncapi.yml"
      origin: "https://api.example.com/asyncapi.json"
      overrides: "./asyncapi-overrides.yml" # or a list of paths
      namespace: "events"
      settings:
        message-naming: "v2"
        title-as-schema-name: false
        respect-nullable-schemas: true
    - asyncapi:
        git:
          repo: https://github.com/org/event-specs.git
          ref: main
          path: asyncapi/events.yml
```

**`asyncapi`** `string | git` — required

Location of the AsyncAPI specification file. Accepts a local file path or a remote git reference.

```yaml
# Local file
asyncapi: ./asyncapi.yml

# Remote git repository
asyncapi:
  git:
    repo: https://github.com/org/event-specs.git
    ref: main
    path: asyncapi/events.yml
```

---

**`asyncapi.git.repo`** `string` — required

The git repository URL (e.g., `https://github.com/org/repo.git`). The CLI shallow-clones this repository at generation time using your system's git credential configuration (credential helpers, SSH keys, `GIT_ASKPASS`).

---

**`asyncapi.git.ref`** `string`

Branch, tag, or commit SHA to check out. Defaults to the repository's default branch when omitted.

---

**`asyncapi.git.path`** `string` — required

Path to the spec file within the repository.

---

**`origin`** `string`

URL of the API definition origin for pulling updates.

---

**`overrides`** `string | list of strings`

Path to an AsyncAPI [overrides](/learn/api-definitions/asyncapi/overrides) file, or a list of paths to multiple override files applied sequentially.

```yaml
# Single override file
overrides: ./asyncapi-overrides.yml

# Multiple override files (applied in order)
overrides:
  - ./base-overrides.yml
  - ./sdk-overrides.yml
```

---

**`namespace`** `string`

Namespace for the specification. Useful for configuring a [single package with multiple API versions](/learn/api-definitions/overview/project-structure#option-2-namespace-based-versioning).

---

**`settings`** `object`

AsyncAPI-specific generation settings for this individual spec. To apply the same settings across all AsyncAPI specs, use global [`api.settings`](/learn/sdks/reference/generators-yml#settings) instead.

---

**`settings.message-naming`** `object` — default: v1

What version of message naming to use for AsyncAPI messages. Options: `v1`, `v2`.

---

**`settings.title-as-schema-name`** `boolean` — default: false

Whether to use the titles of schemas within an AsyncAPI definition as the names of types within Fern.

---

**`settings.respect-nullable-schemas`** `boolean` — default: true

Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.

---

**`settings.idiomatic-request-names`** `boolean` — default: true

Controls the naming convention for autogenerated request names. When enabled, places the verb before the noun in request names (e.g., `UsersListRequest` becomes `ListUsersRequest`), following more idiomatic naming patterns.

---

**`settings.wrap-references-to-nullable-in-optional`** `boolean` — default: false

Controls whether references to nullable schemas are wrapped in optional types. When false, nullable references are treated as required fields that can be null.

---

**`settings.coerce-optional-schemas-to-nullable`** `boolean` — default: false

Controls whether optional schemas are coerced to nullable types during code generation. When false, optional and nullable are treated as distinct concepts.

---

**`settings.group-environments-by-host`** `boolean` — default: false

When enabled, groups servers by host into unified environments, enabling APIs with multiple protocols (REST, WebSocket, etc.) to share environment configuration. Environment URL IDs use the server name, with path or protocol suffixes added only when needed to resolve collisions.

---

#### gRPC/proto buffers

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - proto:
        root: "./proto"
        target: "proto/service/v1/service.proto"
        local-generation: true
    - proto:
        root:
          git:
            repo: https://github.com/org/proto-definitions.git
            ref: v2.3.0
            path: proto/
        target: user/v1/user.proto
```

**`root`** `string | git` — required

Location of the `.proto` directory root. Accepts a local path (e.g., `proto`) or a remote git reference. Must be specified up to where the package starts. For example, if your package is `package.test.v1` at the file path `protos/package/test/v1/test_file.proto`, the root should be `protos/`

```yaml
# Local path
root: ./proto

# Remote git repository
root:
  git:
    repo: https://github.com/org/proto-definitions.git
    ref: v2.3.0
    path: proto/
```

---

**`root.git.repo`** `string` — required

The git repository URL (e.g., `https://github.com/org/repo.git`). The CLI shallow-clones this repository at generation time using your system's git credential configuration (credential helpers, SSH keys, `GIT_ASKPASS`).

---

**`root.git.ref`** `string`

Branch, tag, or commit SHA to check out. Defaults to the repository's default branch when omitted.

---

**`root.git.path`** `string` — required

Path to the `.proto` directory within the repository.

---

**`target`** `string`

Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`). Omit to generate docs for the entire root folder.

---

**`overrides`** `string | list of strings`

Path to the overrides configuration file, or a list of paths to multiple override files applied sequentially. Used for SDK generation only, not for documentation generation.

```yaml
# Single override file
overrides: ./overrides.yml

# Multiple override files (applied in order)
overrides:
  - ./base-overrides.yml
  - ./sdk-overrides.yml
```

---

**`local-generation`** `boolean` — default: false

Whether to compile `.proto` files locally. Defaults to remote generation (`false`). When enabled, you must have [buf](https://buf.build/docs/installation) installed on your machine or in your [CI/CD environment (e.g., GitHub Actions)](/learn/api-definitions/grpc/sync-your-g-rpc-specification).

---

#### OpenRPC

**`.openrpc`** `string` — required

Path to the OpenRPC specification file.

---

**`overrides`** `string | list of strings`

Path to an OpenRPC [overrides](/learn/api-definitions/openrpc/overrides) file, or a list of paths to multiple override files applied sequentially.

```yaml
# Single override file
overrides: ./overrides.yml

# Multiple override files (applied in order)
overrides:
  - ./base-overrides.yml
  - ./sdk-overrides.yml
```

---

**`namespace`** `string`

Namespace for the specification.

---

#### Conjure

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    conjure: "./conjure-api.yml"
```

**`conjure`** `string`

Path to Conjure specification file.

---

## `whitelabel`

Configuration for publishing generated SDKs without Fern branding. When enabled, removes all mentions of Fern from the generated code and allows publishing under your own brand.

**`generators.yml`**

```yaml title="generators.yml"
whitelabel:
  github:
    username: "company-github-username"
    email: "my-email@example.com"
    token: "ghp_xxxxxxxxxxxx"
```

**`username`** `string` — required

The GitHub username that will be used for committing and publishing the whitelabeled SDK code to GitHub repositories. This should be the username of the account that has write access to your target repositories.

---

**`email`** `string` — required

The email address associated with the GitHub account. This email will be used in Git commits when publishing the whitelabeled SDK code and should match the email configured in your GitHub account settings.

---

**`token`** `string` — required

A GitHub Personal Access Token (PAT) with appropriate permissions for repository access. The token should have `repo` scope permissions to allow reading from and writing to your repositories for publishing whitelabeled SDKs.

---

## `metadata`

Package metadata like description and authors that gets included in all generated SDKs. Alternatively, you can [define metadata for individual SDKs](#metadata-2).

**`generators.yml`**

```yaml title="generators.yml"
metadata:
  description: "My API SDK"
  authors:
    - name: "John Doe"
      email: "john@example.com"
    - name: "Jane Smith"
      email: "jane@example.com"
```

**`description`** `string`

A brief description of the SDK that will be included in package metadata. This description helps users understand what your SDK does when they discover it in package repositories.

---

### `authors`

A list of authors who will be credited in the generated SDK's package metadata.

**`name`** `string` — required

The full name of the author to be credited in the SDK package metadata.

---

**`email`** `string` — required

The email address of the author. This will be included in package metadata and may be used by package managers for contact information.

---

## `readme`

Controls what goes into the generated README files across all SDKs, allowing you to customize the content and structure of your SDK documentation.

**`generators.yml`**

```yaml title="generators.yml" maxLines=10
readme:
  bannerLink: "https://example.com/banner"
  introduction: "Welcome to our API"
  apiReferenceLink: "https://docs.example.com"
  apiName: "Example Product"
  exampleStyle: "minimal"
  disabledSections:
    - "contributing"
  defaultEndpoint:
    method: "POST"
    path: "/users"
    stream: false
  customSections:
    - title: "Custom Section"
      language: "java"
      content: |
        This is a custom section. Latest package info is {{ group }}:{{ artifact }}:{{ version }}.
    - title: "Custom Section"
      language: "typescript"
      content: |
        Custom section for {{ packageName }}
    - title: "Another Custom Section"
      language: "typescript"
      content: |
        A second custom section for {{ packageName }}
  features:
    authentication:
      - method: "POST"
        path: "/auth/login"
      - "GET /auth/profile"
    users:
      - method: "GET"
        path: "/users"
      - method: "POST"
        path: "/users"
```

**`bannerLink`** `string`

URL for a banner image or link that appears at the top of the README.

---

**`introduction`** `string`

Custom introduction text that appears at the beginning of the README.

---

**`apiReferenceLink`** `string`

URL to your external API documentation or reference guide.

---

**`apiName`** `string`

Name of the API that appears in the README. Will appear as `Your Api Name SDK` or `Your Api Name API` throughout the README. Defaults to organization name if not set.

---

**`exampleStyle`** `'minimal' | 'comprehensive'` — default: comprehensive

Controls whether usage examples show only required parameters (`minimal`) or all parameters (`comprehensive`). Currently only supported for Java SDKs. [File an issue](https://github.com/fern-api/fern/issues) to request additional languages.

---

**`disabledSections`** `list of strings`

Sections to disable in the README. Supported values: `"contributing"`.

---

**`features`** `list of objects`

Organizes endpoints into named feature sections within the README. Each feature creates a dedicated section with example code snippets for the specified endpoints.

---

#### Endpoint configuration

Specifies which endpoint's code snippet to showcase as the primary example in the README.

**`defaultEndpoint.method`** `string` — required

HTTP method of the default endpoint (e.g., `GET`, `POST`, `PUT`, `DELETE`).

---

**`defaultEndpoint.path`** `string` — required

Endpoint path for the default example (e.g., `/users`, `/auth/login`).

---

**`defaultEndpoint.stream`** `boolean` — default: false

Whether the endpoint is a streaming endpoint. Defaults to `false`.

---

#### Custom sections

Define a custom section in the generated README for a specific SDK.

**`customSections.title`** `string` — required

The title of the custom section as it will appear in the README.

---

**`customSections.language`** `'java' | 'typescript'` — required

The target SDK language for this section. The custom section will only appear in README files generated for the specified language.

---

**`customSections.content`** `string` — required

The Markdown content of the custom section. You can use template variables in the format `{{ variable }}` that will be dynamically replaced with values specific to each SDK language when the README is generated.

Available template variables by language:

| Language   | Variable      | Description                                                                                                                                                                      |
| ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TypeScript | `packageName` | Name of your package, as specified in the [`package-name` field](/learn/sdks/generators/typescript/configuration#package-name)                                                   |
| Python     | `packageName` | Name of your package, as specified in the [`package_name` field](/learn/sdks/generators/python/configuration#package_name)                                                       |
| Go         | `owner`       | The owner of your Go module                                                                                                                                                      |
| Go         | `repo`        | The [repository](/learn/sdks/generators/go/publishing#configure-output-location) where your Go module is published                                                               |
| Go         | `version`     | SDK version                                                                                                                                                                      |
| Java       | `group`       | Maven `groupId` [from `coordinate` field](/learn/sdks/generators/java/publishing#configure-maven-coordinate)                                                                     |
| Java       | `artifact`    | Maven `artifactId` [from `coordinate` field](/learn/sdks/generators/java/publishing#configure-maven-coordinate)                                                                  |
| Java       | `version`     | SDK version                                                                                                                                                                      |
| C#/.NET    | `packageName` | Name of your package, as specified in the [`package-id` field](/learn/sdks/generators/csharp/configuration#package-id)                                                           |
| PHP        | `packageName` | Name of your package, as specified in the [`package-name` field](/learn/sdks/generators/php/configuration#package-name)                                                          |
| Ruby       | `packageName` | Name of your package, as specified in the [`package-name` field](/learn/sdks/generators/ruby/configuration#package-name)                                                         |
| Swift      | `gitUrl`      | The [URL](/learn/sdks/generators/swift/publishing#verify-package-availability) where your Swift package is published. For example, `https://github.com/fern-api/basic-swift-sdk` |
| Swift      | `minVersion`  | SDK version                                                                                                                                                                      |

---

## `default-group`

Which generator group to use when none is specified.

```yaml
default-group: "production"
```

**`default-group`** `string`

---

## `autorelease`

Enable or disable [Fern Autorelease](/learn/sdks/overview/autorelease) globally for automated SDK releases. Alternatively, you can [configure autorelease for individual SDKs](#autorelease-2).

**`generators.yml`**

```yaml title="generators.yml"
autorelease: true
```

**`autorelease`** `boolean`

Set to `true` to enable Autorelease, `false` to disable it. [Per-generator settings](#autorelease-2) override this global configuration.

---

## `replay`

Override [Fern Replay](/learn/sdks/overview/custom-code#replay) behavior. Replay runs based on your organization's configuration; use this setting to disable it for all generators in this `generators.yml`.

**`generators.yml`**

```yaml title="generators.yml"
replay:
  enabled: false
```

**`replay.enabled`** `boolean`

Set to `false` to skip Replay for all SDK generations in this `generators.yml`, even if Replay is enabled for your organization.

---

## `aliases`

Define shortcuts that map to multiple generator groups, allowing you to run several groups with a single command. When you run `fern generate --group <alias>`, all groups in the alias run in parallel. You can also set an alias as your `default-group`.

**`generators.yml`**

```yaml title="generators.yml" {1-4}
aliases:
  all: ["php-sdk", "ts-sdk", "go-sdk"]
  frontend: ["ts-sdk"]
  backend: ["php-sdk", "go-sdk"]

groups:
  php-sdk:
    generators:
      - name: fern-php-sdk
        version: 1.0.0
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
        version: 1.0.0
  go-sdk:
    generators:
      - name: fern-go-sdk
        version: 1.0.0
```

**`aliases`** `map<string, list<string>>`

A map where each key is an alias name and the value is a list of group names. Each group name must reference a group defined in the `groups` section.

---

## `groups`

Organizes user-defined sets of generators, typically grouped by environment (like "production", "staging") or language (like "typescript", "python"). You can also create [aliases](#aliases) to run multiple groups with a single command.

**`generators.yml`**

```yaml title="generators.yml" maxLines=10
groups:
  typescript-sdk: # User-defined name
    audiences: ["external"]
    generators:
      - name: fern-typescript-sdk
        version: 0.9.0
        output:
          location: npm
          package-name: "@myorg/api-sdk"
          token: "${NPM_TOKEN}"
        github:
          repository: your-organization/company-typescript
          mode: "pull-request"
    metadata:
      description: "TypeScript SDK for MyAPI"
      authors:
        - name: "SDK Team"
          email: "sdk@myorg.com"
    reviewers:
      teams:
        - name: "sdk-team"
```

**`audiences`** `list of strings`

Filter which API elements are included in generated SDKs on audience tags. Only endpoints, schemas, and properties tagged with the specified audiences in your API spec will be included. Without this filter, all endpoints are included regardless of their audience tags.

[Filtering your SDKs by audience](/learn/sdks/deep-dives/audiences) takes two steps: [tag your API elements](/learn/api-definitions/openapi/extensions/audiences) in your spec, then list the audiences to include here.

For OpenAPI, you can also configure path-based filtering at the spec level using [`settings.filter`](#settingsfilter).

---

### `reviewers`

Set code reviewers for an individual SDK. Alternatively, you can [configure reviewers globally for all SDKs](#reviewers-4).

**`generators.yml`**

```yaml title="generators.yml"
reviewers:
  teams:
    - name: "sdk-team"
    - name: "api-team"
  users:
    - name: "john-doe"
    - name: "jane-smith"
```

**`teams`** `list of strings`

GitHub team names that should review generated code.

---

**`users`** `list of strings`

GitHub users that should review generated code.

---

**`teams.name`** `string` — required

Name of a GitHub team.

---

**`users.name`** `string` — required

Name of a GitHub user.

---

### `generators`

Generator settings for a specific group.

**`generators.yml`**

```yaml title="generators.yml"
groups:
  typescript-sdk:
    audiences: ["external"]
    generators:
      - name: fern-typescript-sdk
        version: 3.93.1
        smart-casing: true
  python-sdk: # Self-hosted with custom registry
    generators:
      - image:
          name: fern-python-sdk
          registry: ghcr.io/your-org
        version: 5.30.1
```

**`name`** `string` — required

The Fern generator package name (e.g., `fern-typescript-sdk`). Mutually exclusive with `image`.

---

**`version`** `string` — required

Specific version of the generator to use

---

**`smart-casing`** `boolean` — default: false

Enables intelligent case conversion that preserves numbers and common programming patterns:

* Numbers stay intact (e.g., `v2` instead of `v_2`, `getUsersV2` instead of `getUsersV_2`)
* Initialisms are preserved (e.g., `CustomerID` instead of `CustomerId`)
* Acronyms remain correct (e.g., `HTTPSConnection` stays `HTTPSConnection`)

---

**`image`** `object`

Use `image` instead of `name` to pull the generator from a [custom container registry](/learn/sdks/deep-dives/self-hosted#custom-container-registry) during [self-hosted generation](/learn/sdks/deep-dives/self-hosted) (remote generation doesn't support custom registries). Mutually exclusive with `name`.

The CLI constructs the full image reference as `{registry}/{name}:{version}` when pulling. For example, with `registry: ghcr.io/your-org`, `name: fern-python-sdk`, and `version: 4.0.0`, the CLI pulls `ghcr.io/your-org/fern-python-sdk:4.0.0`.

---

**`image.name`** `string` — required

A recognized Fern generator name (e.g., `fern-python-sdk`). Required for IR version resolution.

---

**`image.registry`** `string` — required

The container registry hostname and optional namespace (e.g., `ghcr.io/your-org`). The CLI constructs the full image reference as `{registry}/{name}:{version}` when pulling. For example, with `registry: ghcr.io/your-org`, `name: fern-python-sdk`, and `version: 4.0.0`, the CLI pulls `ghcr.io/your-org/fern-python-sdk:4.0.0`.

---

#### `config`

Language-specific configuration options.

**`generators.yml`**

```yaml title="generators.yml"
groups:
  ts-sdk: # Typescript SDK group
    generators:
      - name: fern-typescript-sdk
        version: 3.93.1
        config: # TypeScript-specific config options
          namespaceExport: AcmePayments
          noSerdeLayer: false
```

#### [TypeScript](/learn/sdks/generators/typescript/configuration)

#### [Python](/learn/sdks/generators/python/configuration)

#### [Go](/learn/sdks/generators/go/configuration)

#### [Java](/learn/sdks/generators/java/configuration)

#### [.NET](/learn/sdks/generators/csharp/configuration)

#### [PHP](/learn/sdks/generators/php/configuration)

#### [Ruby](/learn/sdks/generators/ruby/configuration)

#### [Swift](/learn/sdks/generators/swift/configuration)

#### [Rust](/learn/sdks/generators/rust/configuration)

#### `output`

Where to publish the generated SDK.

**`generators.yml`**

```yaml title="generators.yml"
groups:
  typescript-sdk: # User-defined name
    audiences: ["external"]
    generators:
      - name: fern-typescript-sdk
        version: 0.9.0
        output:
          location: npm
          package-name: "@myorg/api-sdk"
          token: "${NPM_TOKEN}"
```

#### npm

Publish TypeScript SDKs to the npm registry.

**`generators.yml`**

```yaml title="generators.yml"
output:
  location: npm
  package-name: "@myorg/api-sdk"
  token: "${NPM_TOKEN}"
```

**`location`** `'npm'` — required

Set to "npm" for NPM publishing

---

**`url`** `string` — default: npmjs.com

Custom NPM registry URL

---

**`package-name`** `string` — required

NPM package name (e.g., "@myorg/api-sdk")

---

**`token`** `string`

NPM authentication token for publishing

---

#### Maven

Publish Java SDKs to Maven repository.

**`generators.yml`**

```yaml title="generators.yml"
output:
  location: maven
  coordinate: "com.myorg:api-sdk"
  username: "${MAVEN_USERNAME}"
  password: "${MAVEN_PASSWORD}"
  signature:
    keyId: "ABC123"
    password: "${GPG_PASSWORD}"
    secretKey: "${GPG_SECRET_KEY}"
```

**`location`** `'maven'` — required

Set to "maven" for Maven publishing

---

**`url`** `string` — default: npmjs.com

Maven repository URL (optional, defaults to Maven Central)

---

**`coordinate`** `string` — required

Maven artifact coordinate in "groupId:artifactId" format

---

**`username`** `string`

Repository authentication username

---

**`password`** `string`

Repository authentication password

---

**`signature`** `object`

GPG signature configuration for package signing

---

**`signature.keyId`** `string` — required

GPG key ID for package signing

---

**`signature.password`** `string` — required

GPG key password

---

**`signature.secretKey`** `string` — required

GPG secret key content

---

#### PyPI

Publish Python SDKs to Python Package Index.

**`generators.yml`**

```yaml title="generators.yml"
output:
  location: pypi
  package-name: "myorg-api-sdk"
  token: OIDC  # or "${PYPI_TOKEN}" for token-based auth
  metadata:
    keywords: ["api", "sdk", "client"]
    documentation-link: "https://docs.myorg.com"
    homepage-link: "https://myorg.com"
```

**`location`** `'pypi'` — required

Set to "pypi" for PyPI publishing

---

**`url`** `string`

Custom PyPI registry URL (optional, defaults to PyPI)

---

**`package-name`** `string` — required

Python package name (e.g., "myorg-api-sdk")

---

**`token`** `string`

PyPI authentication token. Set to `OIDC` for [trusted publishing](/learn/sdks/generators/python/publishing#configure-authentication) (recommended) or use an environment variable reference (e.g., `${PYPI_TOKEN}`) for token-based auth.

---

**`username`** `string`

PyPI username (alternative to token authentication)

---

**`password`** `string`

PyPI password (alternative to token authentication)

---

**`metadata`** `objecta`

Additional PyPI-specific metadata for the package

---

**`metadata.keywords`** `list of string`

Package keywords for PyPI search and discovery

---

**`metadata.documentation-link`** `string`

Link to package documentation

---

**`metadata.homepage-link`** `string`

Link to project homepage

---

#### NuGet

Publish .NET SDKs to NuGet repository.

**`generators.yml`**

```yaml title="generators.yml"
output:
  location: nuget
  package-name: "MyOrg.ApiSdk"
  api-key: "${NUGET_API_KEY}"
```

**`location`** `'nuget'` — required

Set to "nuget" for NuGet publishing

---

**`url`** `string`

Custom NuGet feed URL (optional, defaults to nuget.org)

---

**`package-name`** `string` — required

NuGet package name (e.g., "MyOrg.ApiSdk")

---

**`api-key`** `string`

NuGet API key for publishing to the feed

---

#### RubyGems

Publish Ruby SDKs to RubyGems registry.

**`generators.yml`**

```yaml title="generators.yml"
output:
  location: rubygems
  package-name: "myorg_api_sdk"
  api-key: "${RUBYGEMS_API_KEY}"
```

**`location`** `'rubygems'` — required

Set to "rubygems" for RubyGems publishing

---

**`url`** `string`

Custom RubyGems registry URL (optional, defaults to rubygems.org)

---

**`package-name`** `string` — required

Ruby gem package name (e.g., "myorg\_api\_sdk")

---

**`api-key`** `string`

RubyGems API key for publishing (requires "Push rubygem" permission)

---

> **Note**: RubyGems API keys need "Push rubygem" permission and ideally "index" and "yank rubygem" permissions. If MFA is enabled, ensure MFA settings don't require MFA for API key usage.

#### Postman

Publish API collections to Postman workspace.

**`generators.yml`**

```yaml title="generators.yml"
output:
  location: postman
  api-key: "${POSTMAN_API_KEY}"
  workspace-id: "12345678-1234-1234-1234-123456789abc"
  collection-id: "87654321-4321-4321-4321-cba987654321"
```

**`location`** `'postman'` — required

Set to "postman" for Postman publishing

---

**`api-key`** `string` — required

Postman API key for workspace access

---

**`workspace-id`** `string` — required

Target Postman workspace ID where collection will be published

---

**`collection-id`** `string`

Existing collection ID to update (creates new collection if not specified)

---

#### Local file system

Save generated SDKs to local file system instead of publishing.

**`generators.yml`**

```yaml title="generators.yml"
output:
  location: local-file-system
  path: "./generated-sdks/typescript"
```

**`location`** `'local-file-system'` — required

Set to "local-file-system" for local output

---

**`path`** `string` — required

Local directory path where generated files will be saved

---

#### `github`

Specify how your SDKs are generated in GitHub using the `github` configuration.
Designate the `mode` to specify how Fern handles your code changes. For cloud generation, specify the GitHub repository using `repository`. For [self-hosted generation](/learn/sdks/deep-dives/self-hosted), use `uri` and `token` instead. Fern doesn't push SDKs to GitLab or other providers; to host elsewhere, generate to your local file system and commit the output from your own pipeline.

Make sure the [Fern GitHub app](https://github.com/apps/fern-api) is installed on your destination repository (not required for self-hosted generation)

#### Release (default)

Fern generates your code, commits it to the default branch (or the `branch` you specify), and tags a new release.

```yml {6-17}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        github: 
          repository: "your-org/your-repo-name"
          mode: "release"
```

**`repository`** `string` — required

Name of your repository in GitHub.

---

**`mode`** `'release'`

---

**`branch`** `string`

If specified, Fern commits and tags the release on this branch instead of the default branch. The branch must already exist. Use this to publish versioned SDKs (e.g., `v1` and `v2`) from a single repo.

---

**`license`** `'MIT' | 'Apache-2.0' | 'Custom License Name'`

Software license for the generated SDK.

---

**`reviewers`** `{ teams: list<string>, users: list<string> }`

Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1).

---

#### Pull request (recommended)

Fern generates your code, commits to a new branch, and opens a PR for review. To publish, you must merge the PR and tag a GitHub release.

```yml {6-8}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        github: 
          repository: "your-org/your-repo-name"
          mode: "pull-request"
```

**`repository`** `string` — required

Name of your repository in GitHub.

---

**`mode`** `'pull-request'`

---

**`branch`** `string`

Name of your branch in GitHub.

---

**`license`** `'MIT' | 'Apache-2.0' | 'Custom License Name'`

Software license for the generated SDK.

---

**`reviewers`** `list of objects`

Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1).

---

#### Push

Fern generates your code and pushes it to the branch you specify.

```yml {6-8}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        github: 
          repository: "your-org/your-repo-name"
          mode: "push"
          branch: "your-branch-name" # required for `mode: push`
```

**`repository`** `string` — required

Name of your repository in GitHub.

---

**`mode`** `'push'`

---

**`branch`** `string` — required

Name of your branch in GitHub.

---

**`license`** `'MIT' | 'Apache-2.0' | 'Custom License Name'`

Software license for the generated SDK.

---

**`reviewers`** `{ teams: list<string>, users: list<string> }`

Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1).

---

#### Self-hosted

For [self-hosted SDK generation](/learn/sdks/deep-dives/self-hosted), configure the `github` property with `uri` and `token` instead of `repository`.

```yml {6-10}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        github: 
          uri: "https://github.com/your-org/your-repo-name"
          token: "${GITHUB_TOKEN}"
          mode: "push"
          branch: "main"
```

**`uri`** `string` — required

Full URL to your GitHub repository (e.g., `https://github.com/your-org/your-repo`).

---

**`token`** `string` — required

GitHub Personal Access Token with repository write permissions. Use an environment variable reference (e.g., `${GITHUB_TOKEN}`).

---

**`mode`** `'push' | 'pull-request'`

How to publish changes: `push` commits directly to the branch, `pull-request` opens a PR for review.

---

**`branch`** `string`

Target branch for commits or pull requests.

---

The following option applies to every `github` mode, including self-hosted generation.

**`workflows`** `boolean` — default: true

Whether generated `.github/workflows/*` files are included in the commit. Set to `false` when the GitHub App or token used for generation lacks the `workflows` permission: GitHub rejects any commit from such a token that adds or modifies workflow files, and `.fernignore` doesn't protect files that don't exist yet in the repository. With `workflows: false`, newly generated workflow files are dropped and tracked workflow files keep their current contents. All other generated files are committed as usual.

```yml {6-8}
groups:
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        github:
          repository: "your-org/your-repo-name"
          workflows: false
```

---

#### `metadata`

Specify metadata for an individual SDK. Alternatively, you can [configure metadata globally for all SDKs](#metadata).

**`generators.yml`**

```yml title="generators.yml" {6-10}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        metadata: 
          package-description: "Description of your SDK"
          email: "sdk@example.com"
          reference-url: "https://docs.example.com/sdks"
          license: "MIT"
```

**`package-description`** `string`

A brief description of what your generated SDK does and its key features. This appears in the `package.json` description field and package registry listings.

---

**`email`** `string`

Contact email for the package maintainer or support team.

---

**`reference-url`** `string`

URL pointing to comprehensive documentation, API reference, or getting started guide for the SDK.

---

**`author`** `string`

Name of the individual developer, team, or organization that created and maintains the SDK.

---

**`license`** `'MIT' | 'Apache-2.0' | 'Custom License Name'`

Software license for the generated SDK.

---

#### `autorelease`

Enable or disable [Fern Autorelease](/learn/sdks/overview/autorelease) for an individual SDK. Alternatively, you can [configure autorelease globally for all SDKs](#autorelease-1).

**`generators.yml`**

```yml title="generators.yml" {6}
groups:
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        autorelease: true
```

**`autorelease`** `boolean`

Set to `true` to enable Autorelease for this generator, `false` to disable it. Per-generator settings override the global [`autorelease`](#autorelease-1) configuration.

---

#### `snippets`

Configures snippets for a particular generator.

**`generators.yml`**

```yml title="generators.yml" {6-8}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        snippets: 
          path: "./snippets"
```

**`path`** `string` — required

The path to the generated snippets file.

---

#### Override API authentication settings

Override authentication settings for a specific SDK using the `api` configuration.

#### Single authentication scheme

Reference a [pre-defined authentication scheme](#auth-schemes) by name.

**`generators.yml`**

```yml title="generators.yml" {6-7}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        api:
          auth: "bearer-token"
```

**`auth`** `string | { scheme: string }`

The authentication scheme to use. Can be either a string reference (`"bearer-token"`) or scheme object (`scheme: "bearer-token"`).

---

#### Multiple authentication options

Allow users to authenticate with any of several methods:

**`generators.yml`**

```yml title="generators.yml" {6-12}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        api:
          auth:
            any:
              - "api-key"
              - "bearer-token"
              - scheme: "oauth-flow"
```

**`any`** `list<string | { scheme: string }>` — required

A list of authentication schemes where users can choose any one method. Each item can be either a string reference (`"api-key"`) or scheme object (`scheme: "api-key"`).

---

#### Custom authentication schemes

Define a custom authentication schemes using `auth-schemes`. You define a name for your custom scheme, and then specify the authentication method (`header`, `basic`, `bearer`, or `oauth`).

**`generators.yml`**

```yml title="generators.yml" {8-12}
groups: 
  ts-sdk:
    generators:
      - name: fern-typescript-sdk
      ...
        api:
          auth-schemes:
            bearer:  # User-defined name for your auth schema
              scheme: "bearer"
              token:
                name: "token"
                env: "BEARER_TOKEN"
```

#### Header authentication

Configure authentication using custom HTTP headers, such as API keys or tokens.

```yaml
auth-schemes:
  api-key: # User-defined scheme name
    name: "API Key Authentication"
    header: "X-API-Key"
    type: "string"
    prefix: "ApiKey "
    env: "MY_API_KEY" # SDK will auto-scan this environment variable
```

**`header`** `string` — required

The name of the HTTP header to use for authentication.

---

**`name`** `string`

A descriptive name for this authentication scheme.

---

**`type`** `string` — default: string

The type of the header value.

---

**`prefix`** `string`

A prefix to prepend to the header value (e.g., `"Bearer "` or `"Token "`).

---

**`env`** `string`

Environment variable name containing the authentication value. When specified, the generated SDK will automatically scan for this environment variable at initialization.

---

#### Basic authentication

Configure HTTP Basic authentication using username and password credentials.

```yaml
auth-schemes:
  basic-auth: # User-defined scheme name
    scheme: basic
    username:
      name: "Username"
      env: "BASIC_AUTH_USERNAME" # SDK will auto-scan this environment variable
    password:
      name: "Password"
      env: "BASIC_AUTH_PASSWORD" # SDK will auto-scan this environment variable
```

**`scheme`** `'basic'` — required

Must be set to `"basic"` for Basic authentication schemes.

---

**`username`** `object`

Configuration for the username credential.

---

**`username.name`** `string`

Custom parameter name for the username in the generated SDK. If not specified, defaults to `"username"`. Use this to provide more descriptive or domain-specific parameter names like `"clientId"`, `"userEmail"`, or `"merchantId"`.

---

**`password`** `object`

Configuration for the password credential.

---

**`password.name`** `string`

Custom parameter name for the password in the generated SDK. If not specified, defaults to `"password"`. Use this to provide more descriptive or domain-specific parameter names like `"clientSecret"`, `"apiKey"`, or `"merchantKey"`.

---

**`username.env, password.env`** `string`

Environment variable name that the SDK will automatically scan for the username or password value. When this environment variable is present, users don't need to explicitly provide the username parameter. Follow naming conventions like `YOUR_APP_USERNAME` or `SERVICE_CLIENT_ID`.

---

**`username.omit, password.omit`** `boolean` — default: false

Use when your API expects only one half of the basic auth credential pair. When `true`, the field is removed from the generated SDK's public API. The omitted field is treated as an empty string when encoding the `Authorization` header (omitting `password` produces `base64("username:")`; omitting `username` produces `base64(":password")`). When both are omitted, the `Authorization` header is skipped entirely.

---

#### Bearer Token Authentication

Configure Bearer token authentication for API access.

```yaml
auth-schemes:
  bearer-token: # User-defined scheme name
    scheme: bearer
    token:
      name: "Access Token"
      env: "BEARER_TOKEN" # SDK will auto-scan this environment variable
```

**`scheme`** `'bearer'` — required

Must be set to `"bearer"` for Bearer token authentication schemes.

---

**`token`** `object`

Configuration for the bearer token.

---

**`token.name`** `string`

A descriptive name for the token.

---

**`token.env`** `string`

Environment variable name containing the bearer token. When specified, the generated SDK will automatically scan for this environment variable at initialization.

---

#### OAuth Client Credentials

For OpenAPI, [OAuth must be configured in `generators.yml`](/learn/api-definitions/openapi/authentication#oauth-client-credentials).

Configure OAuth 2.0 client credentials authentication. Optionally configure a `refresh-token` endpoint for token renewal without re-authentication.

**`generators.yml`**

```yaml title="generators.yml" maxLines=10
auth-schemes:
  my-oauth: # User-defined scheme name
    scheme: oauth
    type: client-credentials
    scopes:
      - "read:users"
      - "write:users"
    client-id-env: "OAUTH_CLIENT_ID" # SDK will auto-scan this environment variable
    client-secret-env: "OAUTH_CLIENT_SECRET" # SDK will auto-scan this environment variable
    token-prefix: "Bearer"
    token-header: "Authorization"
    get-token:
      endpoint: "auth.get_token"
      request-properties:
        client-id: "clientId"
        client-secret: "clientSecret"
        scopes: "scope"
      response-properties:
        access-token: "access_token"
        expires-in: "expires_in"
        refresh-token: "refresh_token"
    refresh-token:
      endpoint: "auth.refresh_token"
      request-properties:
        refresh-token: "refreshToken"
      response-properties:
        access-token: "access_token"
        expires-in: "expires_in"
        refresh-token: "refresh_token"
```

**`scheme`** `'oauth'` — required

Must be set to `"oauth"` for OAuth authentication schemes.

---

**`type`** `'client-credentials'` — required

The OAuth 2.0 grant type. Currently only `"client-credentials"` is supported.

---

**`scopes`** `list of strings`

OAuth scopes to request when obtaining access tokens (e.g., `"read:users"`, `"write:orders"`).

---

**`client-id-env`** `string`

Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization.

---

**`client-secret-env`** `string`

Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization.

---

**`token-prefix`** `string` — default: Bearer

Prefix added to the access token in the Authorization header (e.g., `"Bearer"` results in `"Authorization: Bearer <token>"`). Useful when your API expects a custom format.

---

**`token-header`** `string` — default: Authorization

HTTP header name used to send the access token. Defaults to `"Authorization"` but can be customized if your API uses a different header (e.g., `"X-API-Token"`).

---

##### `get-token`

Specifies the endpoint that exchanges client credentials for an access token. This endpoint is called automatically when the SDK client is initialized.

**`generators.yml`**

```yaml title="generators.yml"
get-token:
  endpoint: "auth.get_token"
  request-properties:
    client-id: "clientId"
    client-secret: "clientSecret"
  response-properties:
    access-token: "access_token"
    expires-in: "expires_in"
```

**`endpoint`** `string` — required

The endpoint that issues access tokens, such as `'auth.get_token'` or `'POST /oauth/token'`. If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `'payments::POST /oauth/token'`).

---

**`request-properties`** `object`

Maps OAuth parameter names to your API's request field names. Use this when your token endpoint expects different field names than the OAuth standard (e.g., your API uses `clientId` instead of `client_id`).

---

**`request-properties.client-id`** `string`

The request field name for the client ID in your API (e.g., `"clientId"`, `"client_id"`).

---

**`request-properties.client-secret`** `string`

The request field name for the client secret in your API (e.g., `"clientSecret"`, `"client_secret"`).

---

**`request-properties.scopes`** `string`

The request field name for scopes in your API (e.g., `"scope"`, `"scopes"`).

---

**`response-properties`** `object`

Maps your API's response field names to OAuth standard names. Use this when your API returns tokens with different field names (e.g., `accessToken` instead of `access_token`).

---

**`response-properties.access-token`** `string`

The response field name for the access token in your API (e.g., `"accessToken"`, `"access_token"`).

---

**`response-properties.expires-in`** `string`

The response field name for token expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). When present, the SDK automatically refreshes tokens before expiration.

---

**`refresh-token`** `string`

The response field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`). Required if using the `refresh-token` flow.

---

##### `refresh-token`

Specifies the endpoint that exchanges a refresh token for a new access token. When configured, the SDK automatically uses this endpoint to renew expired tokens without re-sending credentials. If not configured, the SDK will re-authenticate using `get-token` when tokens expire.

**`generators.yml`**

```yaml title="generators.yml"
refresh-token:
  endpoint: "auth.refresh_token"
  request-properties:
    refresh-token: "refreshToken"
  response-properties:
    access-token: "access_token"
    expires-in: "expires_in"
```

**`endpoint`** `string` — required

The endpoint that refreshes access tokens (e.g., `"POST /oauth/refresh"` or `"auth.refreshToken"`). If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `"payments::POST /oauth/refresh"`).

---

**`request-properties`** `object`

Maps OAuth parameter names to your API's request field names for the refresh flow.

---

**`request-properties.refresh-token`** `string` — required

The request field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`).

---

**`response-properties`** `object`

Maps your API's refresh response field names to OAuth standard names.

---

**`response-properties.access-token`** `string`

The response field name for the new access token (e.g., `"accessToken"`, `"access_token"`).

---

**`response-properties.expires-in`** `string`

The response field name for the new token's expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`).

---

**`response-properties.refresh-token`** `string`

The response field name if your API issues a new refresh token with each refresh (token rotation).

---

### `reviewers`

Set code reviewers globally for all SDKs. Alternatively, you can [configure reviewers for individual SDKs](#reviewers).

**`generators.yml`**

```yaml title="generators.yml"
reviewers:
  teams:
    - name: "sdk-team"
    - name: "api-team"
  users:
    - name: "john-doe"
    - name: "jane-smith"
```

**`teams`** `list of strings`

GitHub team names that should review generated code.

---

**`users`** `list of strings`

GitHub users that should review generated code.

---

**`teams.name`** `string` — required

Name of a GitHub team.

---

**`users.name`** `string` — required

Name of a GitHub user.

---

> Complete generators.yml configuration reference for Fern SDK generation. Configure authentication, publishing, GitHub integration, and language-specific settings.