Reference

generators.yml Configuration Schema

The generators.yml file configures how Fern generates SDKs from your API specification, including which languages to generate, where to publish them, and how to customize each SDK. This document describes the complete configuration schema for generators.yml.

1# Example generators.yml configuration
2api:
3  specs:
4    - openapi: "./openapi.yml"
5      namespace: "v1"
6      settings:
7        title-as-schema-name: true
8        inline-path-parameters: false
9        respect-forward-compatible-enums: true
10
11whitelabel:
12  github:
13    username: "my-org"
14    email: "sdk@mycompany.com"
15    token: "ghp_xxxxxxxxxxxx"
16
17metadata:
18  description: "Official SDK for MyAPI"
19  authors:
20    - name: "SDK Team"
21      email: "sdk@mycompany.com"
22
23readme:
24  introduction: "Welcome to the MyAPI SDK"
25  apiReferenceLink: "https://docs.myapi.com"
26  defaultEndpoint:
27    method: "GET"
28    path: "/users"
29  features:
30    authentication:
31      - "POST /auth/login"
32      - "GET /auth/profile"
33    users:
34      - "GET /users"
35      - "POST /users"
36
37default-group: "production"
38
39groups:
40  production:
41    generators:
42      - name: fernapi/fern-typescript-node-sdk
43        version: 0.9.0
44      - name: fernapi/fern-python-sdk
45        version: 2.0.0

auth-schemes

Define authentication methods for your API. Create named authentication schemes that your endpoints can reference.

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

1auth-schemes:
2  # User-defined scheme name - OAuth with minimal configuration
3  simple-oauth:
4    scheme: oauth
5    type: client-credentials
6    get-token:
7      endpoint: "auth.token"
8    
9  # User-defined scheme name - Header auth with custom configuration
10  custom-header:
11    name: "Custom Auth"
12    header: "X-Custom-Auth"
13    prefix: "Custom "
14    env: "CUSTOM_TOKEN"
15    
16  # User-defined scheme name - Basic auth
17  http-basic:
18    scheme: basic
19    
20  # User-defined scheme name - Bearer token
21  jwt-bearer:
22    scheme: bearer

Header Authentication

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

1auth-schemes:
2  api-key: # User-defined scheme name
3    name: "API Key Authentication"
4    header: "X-API-Key"
5    type: "string"
6    prefix: "ApiKey "
7    env: "MY_API_KEY" # SDK will auto-scan this environment variable
header
stringRequired

The name of the HTTP header to use for authentication.

name
string

A descriptive name for this authentication scheme.

type
stringDefaults to 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.

1auth-schemes:
2  basic-auth: # User-defined scheme name
3    scheme: basic
4    username:
5      name: "Username"
6      env: "BASIC_AUTH_USERNAME" # SDK will auto-scan this environment variable
7    password:
8      name: "Password"
9      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.

Bearer Token Authentication

Configure Bearer token authentication for API access.

1auth-schemes:
2  bearer-token: # User-defined scheme name
3    scheme: bearer
4    token:
5      name: "Access Token"
6      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 Authentication

Configure OAuth 2.0 client credentials authentication.

1auth-schemes:
2  my-oauth: # User-defined scheme name
3    scheme: oauth
4    type: client-credentials
5    scopes:
6      - "read:users"
7      - "write:users"
8    client-id-env: "OAUTH_CLIENT_ID" # SDK will auto-scan this environment variable
9    client-secret-env: "OAUTH_CLIENT_SECRET" # SDK will auto-scan this environment variable
10    token-prefix: "Bearer"
11    token-header: "Authorization"
12    get-token:
13      endpoint: "auth.get_token"
14      request-properties:
15        client-id: "clientId"
16        client-secret: "clientSecret"
17        scopes: "scope"
18      response-properties:
19        access-token: "access_token"
20        expires-in: "expires_in"
21        refresh-token: "refresh_token"
22    refresh-token:
23      endpoint: "auth.refresh_token"
24      request-properties:
25        refresh-token: "refreshToken"
26      response-properties:
27        access-token: "access_token"
28        expires-in: "expires_in"
29        refresh-token: "refresh_token"
scheme
'oauth'Required

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

type
literal<'client-credentials'>Required

The OAuth flow type. Currently only "client-credentials" is supported.

scopes
list<string>

List of OAuth scopes to request during authentication.

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
stringDefaults to Bearer

Sets the token header value prefix.

token-header
stringDefaults to Authorization

Sets the token header key name.

get-token

Configuration for the token acquisition endpoint.

1get-token:
2  endpoint: "auth.get_token"
3  request-properties:
4    client-id: "clientId"
5    client-secret: "clientSecret"
6  response-properties:
7    access-token: "access_token"
8    expires-in: "expires_in"
endpoint
stringRequired

The endpoint to get the access token, such as 'auth.get_token'.

request-properties
object

Customizes the property names used in the token request.

client-id
string

The property name for the client ID in the request.

client-secret
string

The property name for the client secret in the request.

scopes
string

The property name for the scopes in the request.

response-properties
object

Maps custom property names in your OAuth token response (e.g., if your API returns accessToken instead of access_token).

access-token
string

The property name for the access token in the response.

expires-in
string

The property name for the expires in property in the response.

refresh-token
string

The property name for the refresh token in the response.

refresh-token

Configuration for the token refresh endpoint.

1refresh-token:
2  endpoint: "auth.refresh_token"
3  request-properties:
4    refresh-token: "refreshToken"
5  response-properties:
6    access-token: "access_token"
7    expires-in: "expires_in"
endpoint
stringRequired

The endpoint to refresh the access token, such as 'auth.refresh_token'.

request-properties
object

Maps custom property names in your refresh token request.

refresh-token
stringRequired

The property name for the refresh token in the request.

response-properties
object

Maps custom property names in your refresh token response.

access-token
string

The property name for the access token in the response.

expires-in
string

The property name for the expires in property in the response.

refresh-token
string

The property name for the refresh token in the response.

api

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

1api:
2  specs:
3    - openapi: "./openapi.yml"
4      namespace: "v1"
5      settings:
6        title-as-schema-name: true
7        inline-path-parameters: false
8    - asyncapi: "./events.yml"
9      namespace: "events"
10  headers:
11    Authorization: "Bearer ${API_TOKEN}"
12  environments:
13    production: "https://api.prod.com"
14    staging: "https://api.staging.com"
specs
list<SpecSchema> | ConjureSchemaRequired

List of API specifications or Conjure configuration.

auth
ApiAuthSchema

Authentication configuration for the API.

headers
map<string, HeaderValue>

Global headers to include with all API requests. You can specify headers as simple string values or as objects with additional configuration for code generation.

Simple string values:

1api:
2  headers:
3    Authorization: "Bearer ${API_TOKEN}"
4    X-App-Version: "1.0.0"

Advanced configuration with type information:

1api:
2  - openapi: ./path/to/openapi
3    headers: 
4      X-Version: 
5        # The variable name to use in generated SDK code. 
6        # If not specified, uses the header name.
7        name: version 
8        # The type of the header value for code generation 
9        # (e.g., "string", "literal<'value'>", "number").
10        type: literal<"1234">
environments
EnvironmentsSchema

Environment configurations for different deployment targets.

Specification Types

OpenAPI

1api:
2  specs:
3    - openapi: "./openapi.yml"
4      origin: "https://api.example.com/openapi.json"
5      overrides: "./openapi-overrides.yml"
6      namespace: "v1"
7      settings:
8        title-as-schema-name: true
9        inline-path-parameters: false
10        prefer-undiscriminated-unions-with-literals: true
11        filter:
12          endpoints: ["POST /users", "GET /users/{id}"]
13        example-generation:
14          request:
15            max-depth: 2
openapi
stringRequired

Path to the OpenAPI specification file.

origin
string

URL of the API definition origin for polling updates.

overrides
string

Path to OpenAPI overrides file.

namespace
string

Namespace for the specification.

settings
OpenAPISettingsSchema

OpenAPI-specific generation settings.

title-as-schema-name
booleanDefaults to true

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

inline-path-parameters
booleanDefaults to false

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

prefer-undiscriminated-unions-with-literals
booleanDefaults to false

Whether to prefer undiscriminated unions with literals.

only-include-referenced-schemas
booleanDefaults to false

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

respect-nullable-schemas
booleanDefaults to false

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

object-query-parameters
boolean

Enables parsing deep object query parameters.

respect-readonly-schemas
boolean

Enables exploring readonly schemas in OpenAPI specifications.

respect-forward-compatible-enums
booleanDefaults to false

Enables respecting forward compatible enums in OpenAPI specifications.

use-bytes-for-binary-response
boolean

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

default-form-parameter-encoding
FormParameterEncodingDefaults to json

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

additional-properties-defaults-to
booleanDefaults to false

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

type-dates-as-strings
booleanDefaults to true

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

preserve-single-schema-oneof
booleanDefaults to false

If true, preserve oneOf structures with a single schema. If false, unwrap them.

filter.endpoints
list<string>

Endpoints to include in the generated SDK (e.g., “POST /users”).

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.

example-generation.response.max-depth
integer

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

AsyncAPI

1api:
2  specs:
3    - asyncapi: "./asyncapi.yml"
4      origin: "https://api.example.com/asyncapi.json"
5      overrides: "./asyncapi-overrides.yml"
6      namespace: "events"
7      settings:
8        message-naming: "v2"
9        title-as-schema-name: false
10        respect-nullable-schemas: true
asyncapi
stringRequired

Path to the AsyncAPI specification file.

origin
string

URL of the API definition origin for polling updates.

overrides
string

Path to AsyncAPI overrides file.

namespace
string

Namespace for the specification.

settings
AsyncAPISettingsSchema

AsyncAPI-specific generation settings.

message-naming
MessageNamingSettingsSchemaDefaults to v1

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

title-as-schema-name
booleanDefaults to true

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

respect-nullable-schemas
booleanDefaults to false

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

Protocol Buffers

1api:
2  specs:
3    - proto:
4        root: "./proto"
5        target: "proto/service/v1/service.proto"
6        local-generation: true
proto
ProtobufDefinitionSchemaRequired

Protocol Buffers configuration.

target
string

Path to the target .proto file (e.g., proto/user/v1/user.proto).

root
stringRequired

Path to the .proto directory root (e.g., proto).

overrides
string

Path to the overrides configuration.

local-generation
boolean

Whether to compile .proto files locally. Defaults to remote generation.

OpenRPC

.openrpc
stringRequired

Path to the OpenRPC specification file.

overrides
string

Path to OpenRPC overrides file.

namespace
string

Namespace for the specification.

Conjure

1api:
2  specs:
3    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.

1whitelabel:
2  github:
3    username: "company-github-username"
4    email: "my-email@example.com"
5    token: "ghp_xxxxxxxxxxxx"
username
stringRequired

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
stringRequired

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
stringRequired

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 generated SDKs.

1metadata:
2  description: "My API SDK"
3  authors:
4    - name: "John Doe"
5      email: "john@example.com"
6    - name: "Jane Smith"
7      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
stringRequired

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

email
stringRequired

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.

1readme:
2  bannerLink: "https://example.com/banner"
3  introduction: "Welcome to our API"
4  apiReferenceLink: "https://docs.example.com"
5  defaultEndpoint:
6    method: "POST"
7    path: "/users"
8    stream: false
9  features:
10    authentication:
11      - method: "POST"
12        path: "/auth/login"
13      - "GET /auth/profile"
14    users:
15      - method: "GET"
16        path: "/users"
17      - method: "POST"
18        path: "/users"
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.

string

URL to your external API documentation or reference guide.

defaultEndpoint
ReadmeEndpointSchema

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

features
map<string, list<ReadmeEndpointSchema>>

Groups endpoints by feature name for organized README sections. Each feature becomes a section in the README with example code snippets for the listed endpoints.

defaultEndpoint

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

method
stringRequired

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

path
stringRequired

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

stream
booleanDefaults to false

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

default-group

Which group to use when none is specified.

1default-group: "production"
default-group
string

groups

Organizes user-defined sets of generators, typically grouped by environment (like “production”, “staging”) or language (like “typescript”, “python”).

1groups:
2  company-typescript: # User-defined name
3    audiences: ["external"]
4    generators:
5      - name: fernapi/fern-typescript-node-sdk
6        version: 0.9.0
7        output:
8          location: npm
9          package-name: "@myorg/api-sdk"
10          token: "${NPM_TOKEN}"
11        github:
12          repository: your-organization/company-typescript
13          mode: "pull-request"
14    metadata:
15      description: "TypeScript SDK for MyAPI"
16      authors:
17        - name: "SDK Team"
18          email: "sdk@myorg.com"
19    reviewers:
20      teams:
21        - name: "sdk-team"
audiences
string[]

Target audiences for this generator group (e.g., “external”, “internal”)

reviewers

Who should review generated code for a specific group.

1reviewers:
2  teams:
3    - name: "sdk-team"
4    - name: "api-team"
5  users:
6    - name: "john-doe"
7    - name: "jane-smith"
teams
list<string>

GitHub team names that should review generated code.

users
list<string>

GitHub users that should review generated code.

name
stringRequired

Name of a GitHub team or a user.

generators

1groups:
2  company-typescript: # User-defined name
3    audiences: ["external"]
4    generators:
5      - name: fernapi/fern-typescript-node-sdk
6        version: 0.9.0

Individual generator settings within a group.

name
stringRequired

The Fern generator package name (e.g., fernapi/fern-typescript-node-sdk)

version
stringRequired

Specific version of the generator to use

output

Configuration for where and how to publish the generated SDK

1groups:
2  company-typescript: # User-defined name
3    audiences: ["external"]
4    generators:
5      - name: fernapi/fern-typescript-node-sdk
6        version: 0.9.0
7        output:
8          location: npm
9          package-name: "@myorg/api-sdk"
10          token: "${NPM_TOKEN}"

Publish TypeScript/JavaScript SDKs to NPM registry.

1output:
2  location: npm
3  package-name: "@myorg/api-sdk"
4  token: "${NPM_TOKEN}"
location
'npm'Required

Set to “npm” for NPM publishing

url
stringDefaults to npmjs.com

Custom NPM registry URL

package-name
stringRequired

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

token
string

NPM authentication token for publishing

Publish Java SDKs to Maven repository.

1output:
2  location: maven
3  coordinate: "com.myorg:api-sdk"
4  username: "${MAVEN_USERNAME}"
5  password: "${MAVEN_PASSWORD}"
6  signature:
7    keyId: "ABC123"
8    password: "${GPG_PASSWORD}"
9    secretKey: "${GPG_SECRET_KEY}"
location
'maven'Required

Set to “maven” for Maven publishing

url
stringDefaults to npmjs.com

Maven repository URL (optional, defaults to Maven Central)

coordinate
stringRequired

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
stringRequired

GPG key ID for package signing

signature.password
stringRequired

GPG key password

signature.secretKey
stringRequired

GPG secret key content

Publish Python SDKs to Python Package Index.

1output:
2  location: pypi
3  package-name: "myorg-api-sdk"
4  token: "${PYPI_TOKEN}"
5  metadata:
6    keywords: ["api", "sdk", "client"]
7    documentation-link: "https://docs.myorg.com"
8    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
stringRequired

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

token
string

PyPI authentication token for publishing

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
string[]

Package keywords for PyPI search and discovery

metadata.documentation-link
string

Link to package documentation

metadata.homepage-link
string

Link to project homepage

Publish .NET SDKs to NuGet repository.

1output:
2  location: nuget
3  package-name: "MyOrg.ApiSdk"
4  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
stringRequired

NuGet package name (e.g., “MyOrg.ApiSdk”)

api-key
string

NuGet API key for publishing to the feed

Publish Ruby SDKs to RubyGems registry.

1output:
2  location: rubygems
3  package-name: "myorg_api_sdk"
4  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
stringRequired

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.

Publish API collections to Postman workspace.

1output:
2  location: postman
3  api-key: "${POSTMAN_API_KEY}"
4  workspace-id: "12345678-1234-1234-1234-123456789abc"
5  collection-id: "87654321-4321-4321-4321-cba987654321"
location
'postman'Required

Set to “postman” for Postman publishing

api-key
stringRequired

Postman API key for workspace access

workspace-id
stringRequired

Target Postman workspace ID where collection will be published

collection-id
string

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

Save generated SDKs to local file system instead of publishing.

1output:
2  location: local-file-system
3  path: "./generated-sdks/typescript"
location
'local-file-system'Required

Set to “local-file-system” for local output

path
stringRequired

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 specifiy how Fern handles your code changes. For all of the modes, you must specify the GitHub repository in which you want to store your SDK code. You can also configure a branch name, license, and reviewers.

Make sure the Fern GitHub app is installed on your destination repository

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.

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        github: 
7          repository: "your-org/your-repo-name"
8          mode: "pull-request"
repository
stringRequired
mode
'pull-request'
branch
string
license
'MIT' | 'Apache-2.0' | { custom: 'Custom License Name' }
reviewers
{ teams: list<string>, users: list<string> }

Specify which teams and users should review generated code. See reviewers configuration.

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

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        github: 
7          repository: "your-org/your-repo-name"
8          mode: "push"
9          branch: "your-branch-name" # required for `mode: push`
repository
stringRequired
mode
'push'
branch
stringRequired
license
'MIT' | 'Apache-2.0' | { custom: 'Custom License Name' }
reviewers
{ teams: list<string>, users: list<string> }

Specify which teams and users should review generated code. See reviewers configuration.

metadata

Specify metadata for your SDK generator.

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        metadata: 
7          package-description: "Description of your SDK"
8          email: "sdk@example.com"
9          reference-url: "https://docs.example.com/sdks"
10          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: 'Custom License Name' }

Software license for the generated SDK.

snippets

Configures snippets for a particular generator.

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        snippets: 
7          path: "./snippets"
path
stringRequired

The path to the generated snippets file.

Override API Authentication Settings

Override authentication settings in your API spec using the api configuration. You can specify authentication schemes, reference existing auth configurations, and set additional API-specific settings.

Reference a pre-defined authentication scheme by name.

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        api:
7          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").

Allow users to authenticate with any of several methods:

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        api:
7          auth:
8            any:
9              - "api-key"
10              - "bearer-token"
11              - 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").

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

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        api:
7          auth-schemes:
8            bearer:  # User-defined name for your auth schema
9              scheme: "bearer"
10              token:
11                name: "token"
12                env: "BEARER_TOKEN"

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

1auth-schemes:
2  api-key: # User-defined scheme name
3    name: "API Key Authentication"
4    header: "X-API-Key"
5    type: "string"
6    prefix: "ApiKey "
7    env: "MY_API_KEY" # SDK will auto-scan this environment variable
header
stringRequired

The name of the HTTP header to use for authentication.

name
string

A descriptive name for this authentication scheme.

type
stringDefaults to 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.

Configure HTTP Basic authentication using username and password credentials.

1auth-schemes:
2  basic-auth: # User-defined scheme name
3    scheme: basic
4    username:
5      name: "Username"
6      env: "BASIC_AUTH_USERNAME" # SDK will auto-scan this environment variable
7    password:
8      name: "Password"
9      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.

Configure Bearer token authentication for API access.

1auth-schemes:
2  bearer-token: # User-defined scheme name
3    scheme: bearer
4    token:
5      name: "Access Token"
6      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.

Configure OAuth 2.0 client credentials authentication.

1auth-schemes:
2  my-oauth: # User-defined scheme name
3    scheme: oauth
4    type: client-credentials
5    scopes:
6      - "read:users"
7      - "write:users"
8    client-id-env: "OAUTH_CLIENT_ID" # SDK will auto-scan this environment variable
9    client-secret-env: "OAUTH_CLIENT_SECRET" # SDK will auto-scan this environment variable
10    token-prefix: "Bearer"
11    token-header: "Authorization"
12    get-token:
13      endpoint: "auth.get_token"
14      request-properties:
15        client-id: "clientId"
16        client-secret: "clientSecret"
17        scopes: "scope"
18      response-properties:
19        access-token: "access_token"
20        expires-in: "expires_in"
21        refresh-token: "refresh_token"
22    refresh-token:
23      endpoint: "auth.refresh_token"
24      request-properties:
25        refresh-token: "refreshToken"
26      response-properties:
27        access-token: "access_token"
28        expires-in: "expires_in"
29        refresh-token: "refresh_token"
scheme
'oauth'Required

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

type
literal<'client-credentials'>Required

The OAuth flow type. Currently only "client-credentials" is supported.

scopes
list<string>

List of OAuth scopes to request during authentication.

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
stringDefaults to Bearer

Sets the token header value prefix.

token-header
stringDefaults to Authorization

Sets the token header key name.

get-token

Configuration for the token acquisition endpoint.

1get-token:
2  endpoint: "auth.get_token"
3  request-properties:
4    client-id: "clientId"
5    client-secret: "clientSecret"
6  response-properties:
7    access-token: "access_token"
8    expires-in: "expires_in"
endpoint
stringRequired

The endpoint to get the access token, such as 'auth.get_token'.

request-properties
object

Customizes the property names used in the token request.

client-id
string

The property name for the client ID in the request.

client-secret
string

The property name for the client secret in the request.

scopes
string

The property name for the scopes in the request.

response-properties
object

Maps custom property names in your OAuth token response (e.g., if your API returns accessToken instead of access_token).

access-token
string

The property name for the access token in the response.

expires-in
string

The property name for the expires in property in the response.

refresh-token
string

The property name for the refresh token in the response.

refresh-token

Configuration for the token refresh endpoint.

1refresh-token:
2  endpoint: "auth.refresh_token"
3  request-properties:
4    refresh-token: "refreshToken"
5  response-properties:
6    access-token: "access_token"
7    expires-in: "expires_in"
endpoint
stringRequired

The endpoint to refresh the access token, such as 'auth.refresh_token'.

request-properties
object

Maps custom property names in your refresh token request.

refresh-token
stringRequired

The property name for the refresh token in the request.

response-properties
object

Maps custom property names in your refresh token response.

access-token
string

The property name for the access token in the response.

expires-in
string

The property name for the expires in property in the response.

refresh-token
string

The property name for the refresh token in the response.

reviewers

Who should review generated code for all groups.

1reviewers:
2  teams:
3    - name: "sdk-team"
4    - name: "api-team"
5  users:
6    - name: "john-doe"
7    - name: "jane-smith"
teams
list<string>

GitHub team names that should review generated code.

users
list<string>

GitHub users that should review generated code.

name
stringRequired

Name of a GitHub team or a user.