From ed0aab307e8cdfc470eb1102e5439b37979782f8 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 20 Jan 2026 23:11:40 +0000 Subject: [PATCH 1/5] docs: improve api.auth documentation with complete example - Expand api.auth ParamField to explain what it does and what values it accepts - Add complete example showing the two-step workflow: define scheme, then apply it - Add Note in auth-schemes section pointing users to api.auth - Include SDK usage example showing the result Co-Authored-By: kenny@buildwithfern.com --- .../reference/generators-yml-reference.mdx | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 1b3945761..6ab903743 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -59,6 +59,10 @@ Define authentication methods for your API that your endpoints can reference. Au Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication. + + After defining an authentication scheme, use [`api.auth`](#auth) to apply it as the default for all endpoints. + + Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings). @@ -132,8 +136,38 @@ api: staging: "https://api.staging.com" ``` - - Authentication configuration for the API. + + Sets the default authentication scheme for all endpoints. The value must reference a scheme name defined in [`auth-schemes`](#auth-schemes). This overrides any security schemes defined in your OpenAPI spec. + + ```yaml title="generators.yml" + # Step 1: Define your authentication scheme + auth-schemes: + BearerAuth: + scheme: bearer + token: + name: apiKey + env: PLANTSTORE_API_KEY + + # Step 2: Apply it as the default for all endpoints + api: + auth: BearerAuth + specs: + - openapi: ./openapi.yml + ``` + + With this configuration, all generated SDKs will require authentication using the `BearerAuth` scheme: + + ```ts + // Uses process.env.PLANTSTORE_API_KEY + const client = new PlantStoreClient(); + + // Or provide the API key explicitly + const client = new PlantStoreClient({ + apiKey: "your-api-key" + }); + ``` + + You can also override authentication for individual generators using the [generator-level `api.auth`](#override-api-authentication-settings) setting. From 1917112e7978c97689b23f94a4bfc29a54f68d57 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 19:21:56 +0000 Subject: [PATCH 2/5] docs: improve OpenAPI auth page with clearer api.auth documentation - Add Note at top of page pointing users to generators.yml for setting default auth - Rename 'Override security scheme' to 'Set default authentication in generators.yml' - Add complete two-step example showing how to define and apply auth schemes - Include SDK usage example showing the result - Add cross-references to generators.yml reference for full details Co-Authored-By: kenny@buildwithfern.com --- fern/products/api-def/openapi-pages/auth.mdx | 42 +++++++++++++++----- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index 2ab64b705..8a5d7dc4e 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -19,6 +19,10 @@ security: All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials. Authentication schemes are also automatically supported in the [API Explorer](/learn/docs/api-references/api-explorer/overview#authentication), including multiple schemes and combinations. + +You can also define authentication in `generators.yml` using [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes) and apply it as the default for all endpoints with [`api.auth`](/learn/sdks/reference/generators-yml#auth). This is useful for customizing SDK parameter names, environment variables, or configuring OAuth. + + ## Bearer security scheme Define a `bearer` security scheme in your `openapi.yml`: @@ -262,26 +266,46 @@ In this example, users can authenticate with either a bearer token OR with both When using [OAuth client credentials](#oauth-client-credentials) with multiple authentication schemes, ensure the scheme name in your OpenAPI spec's `security` section matches the name defined in your `generators.yml` auth-schemes configuration. -## Override security scheme +## Set default authentication in generators.yml -You can use `generators.yml` to define custom authentication schemes that will take precedence when generating SDKs. This is also how OAuth authentication is configured for OpenAPI specs. +You can use `generators.yml` to define authentication schemes and set a default for all endpoints. This approach lets you customize SDK parameter names, environment variables, and is required for OAuth configuration. -First, use the `auth-schemes` property to define your authentication scheme. Then, specify your auth scheme in the `api` property to override your OpenAPI spec. +Authentication in `generators.yml` is configured in two steps: + +1. **Define your scheme** in `auth-schemes` +2. **Apply it as the default** with `api.auth` ```yml title="generators.yml" +# Step 1: Define your authentication scheme auth-schemes: - bearerAuth: # Must match the name used in your OpenAPI security section + BearerAuth: scheme: bearer token: name: apiKey # Custom parameter name in the SDK - env: YOUR_TOKEN_NAME # Environment variable to auto-scan + env: PLANTSTORE_API_KEY # Environment variable to auto-scan + +# Step 2: Apply it as the default for all endpoints api: - auth: bearerAuth # Reference the same name from your OpenAPI spec + auth: BearerAuth + specs: + - openapi: ./openapi.yml +``` + +With this configuration, all generated SDKs will require authentication: + +```ts +// Uses process.env.PLANTSTORE_API_KEY +const client = new PlantStoreClient(); + +// Or provide the API key explicitly +const client = new PlantStoreClient({ + apiKey: "your-api-key" +}); ``` - -When overriding a security scheme in `generators.yml`, the name must match the scheme name referenced in your OpenAPI spec's `security` section. For example, if your OpenAPI spec uses `security: - bearerAuth: []`, then use `auth: bearerAuth` in generators.yml. - + +Authentication schemes defined in `generators.yml` take precedence over schemes defined in your OpenAPI spec. For the full reference, see [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes) and [`api.auth`](/learn/sdks/reference/generators-yml#auth). + ### Auth scheme reference From 952f6e42128a3181059e067c7fa7508071bf09b5 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 4 Feb 2026 16:38:51 -0500 Subject: [PATCH 3/5] clarify and restructure info --- fern/products/api-def/openapi-pages/auth.mdx | 319 +++++++++--------- .../reference/generators-yml-reference.mdx | 42 +-- 2 files changed, 175 insertions(+), 186 deletions(-) diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index 8a5d7dc4e..0355873e6 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -1,42 +1,48 @@ --- title: Authentication -description: Model auth schemes such as bearer, basic, api key, and OAuth. -max-toc-depth: 2 +description: 'Model auth schemes such as bearer, basic, api key, and OAuth.' --- -Authentication in OpenAPI is configured in two steps: first, define your schemes in `components.securitySchemes`, then apply them either globally or per-endpoint using the `security` property. +Fern supports two ways to configure authentication for your API: -```yml title="openapi.yml" {2-5, 7-8} +- **In your OpenAPI spec** using `securitySchemes` — the standard approach that keeps auth configuration portable and works with other OpenAPI tools. +- **In `generators.yml`** using `auth-schemes` — use this to customize SDK parameter names and environment variables, override what's defined in your spec, or configure OAuth (which isn't available in OpenAPI). + +If you define the same scheme in both places, `generators.yml` takes precedence. This is useful when your spec is auto-generated or you want SDK behavior to differ from your spec. + + +All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials. Authentication schemes are also automatically supported in the [API Explorer](/learn/docs/api-references/api-explorer/overview#authentication). + + +## Configure authentication in your spec + +Define your schemes in `components.securitySchemes`, then apply them globally or per-endpoint using the `security` property. + +```yml title="openapi.yml" +# Define the scheme components: securitySchemes: - AuthScheme: + BearerAuth: # User-defined scheme name type: http scheme: bearer + # Apply globally across all endpoints security: - - AuthScheme: [] + - BearerAuth: [] ``` -All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials. Authentication schemes are also automatically supported in the [API Explorer](/learn/docs/api-references/api-explorer/overview#authentication), including multiple schemes and combinations. - - -You can also define authentication in `generators.yml` using [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes) and apply it as the default for all endpoints with [`api.auth`](/learn/sdks/reference/generators-yml#auth). This is useful for customizing SDK parameter names, environment variables, or configuring OAuth. - - -## Bearer security scheme - -Define a `bearer` security scheme in your `openapi.yml`: + + -```yml title="openapi.yml" {3-5} +```yml title="openapi.yml" components: securitySchemes: - BearerAuth: + BearerAuth: # User-defined scheme name type: http scheme: bearer ``` -This will generate an SDK where the user would have to provide -a mandatory argument called `token`. +Generated SDK usage: ```ts index.ts const client = new Client({ @@ -44,10 +50,9 @@ const client = new Client({ }) ``` -If you want to control variable naming and the environment variable to scan, -use the configuration below: +To customize parameter names and environment variables, add `x-fern-bearer`: -```yaml title="openapi.yml" {6-8} +```yaml title="openapi.yml" components: securitySchemes: BearerAuth: @@ -58,48 +63,42 @@ components: env: PLANTSTORE_API_KEY ``` -The generated SDK would look like: - ```ts index.ts - // Uses process.env.PLANTSTORE_API_KEY let client = new Client(); -// token has been renamed to apiKey +// Parameter renamed from 'token' to 'apiKey' client = new Client({ apiKey: "ey34..." }) ``` -## Basic security scheme - -Define a `basic` security scheme in your `openapi.yml`: + + -```yaml title="openapi.yml" {3-5} +```yaml title="openapi.yml" components: securitySchemes: - BasicAuth: + BasicAuth: # User-defined scheme name type: http scheme: basic ``` -This will generate an SDK where the user would have to provide -a mandatory arguments called `username` and `password`. +Generated SDK usage: ```ts index.ts const client = new Client({ - username: "joeschmoe" + username: "joeschmoe", password: "ey34..." }) ``` -If you want to control variable naming and environment variables to scan, -use the configuration below: +To customize parameter names and environment variables, add `x-fern-basic`: -```yaml title="openapi.yml" {6-12} +```yaml title="openapi.yml" components: securitySchemes: - BasicAuth: + BasicAuth: type: http scheme: basic x-fern-basic: @@ -111,35 +110,30 @@ components: env: PLANTSTORE_CLIENT_SECRET ``` -The generated SDK would look like: - ```ts index.ts - // Uses process.env.PLANTSTORE_CLIENT_ID and process.env.PLANTSTORE_CLIENT_SECRET let client = new Client(); -// parameters have been renamed +// Parameters renamed client = new Client({ clientId: "joeschmoe", clientSecret: "ey34..." }) ``` -## ApiKey security scheme - -Define an `apiKey` security scheme in your `openapi.yml`: + + -```yml title="openapi.yml" {3-5} +```yml title="openapi.yml" components: securitySchemes: - ApiKey: + ApiKeyAuth: # User-defined scheme name type: apiKey in: header name: X_API_KEY ``` -This will generate an SDK where the user would have to provide -a mandatory argument called `apiKey`. +Generated SDK usage: ```ts index.ts const client = new Client({ @@ -147,188 +141,195 @@ const client = new Client({ }) ``` -If you want to control variable naming and environment variables to scan, -use the configuration below: +To customize parameter names and environment variables, add `x-fern-header`: -```yaml title="openapi.yml" {7-10} +```yaml title="openapi.yml" components: securitySchemes: - ApiKey: + ApiKeyAuth: type: apiKey in: header name: X_API_KEY x-fern-header: name: apiToken env: PLANTSTORE_API_KEY - prefix: "Token " # Optional + prefix: "Token " ``` - - The `prefix` option lets you automatically add a prefix to API keys. This is useful when your API expects tokens in a specific format like `"Bearer abc123"` or `"Token abc123"`. - - -The generated SDK would look like: - ```ts index.ts - // Uses process.env.PLANTSTORE_API_KEY let client = new Client(); -// parameters have been renamed +// Parameter renamed from 'apiKey' to 'apiToken' client = new Client({ apiToken: "ey34..." }) ``` -## OAuth client credentials - - - -Configure OAuth 2.0 client credentials in `generators.yml` rather than in the API specification: - -```yaml title="generators.yml" maxLines=10 -auth-schemes: - OAuth: - scheme: oauth - type: client-credentials - client-id-env: "OAUTH_CLIENT_ID" - client-secret-env: "OAUTH_CLIENT_SECRET" - get-token: - endpoint: "POST /oauth/token" - request-properties: - client-id: "client_id" - client-secret: "client_secret" - response-properties: - access-token: "access_token" - expires-in: "expires_in" - refresh-token: "refresh_token" - refresh-token: - endpoint: "POST /oauth/refresh" - request-properties: - refresh-token: "refresh_token" - response-properties: - access-token: "access_token" - expires-in: "expires_in" -api: - auth: OAuth -``` - - -The `endpoint` values (e.g., `"POST /oauth/token"`) reference paths defined in your OpenAPI specification. When `expires-in` is returned, the SDK will automatically refresh tokens before they expire. For more details on OAuth configuration options, see the [Auth scheme reference](#auth-scheme-reference) below. - - -The generated SDK would look like: - -```ts index.ts - -// Uses process.env.OAUTH_CLIENT_ID and process.env.OAUTH_CLIENT_SECRET -let client = new Client(); - -// Or provide credentials explicitly -client = new Client({ - clientId: "your_client_id", - clientSecret: "your_client_secret" -}) + +The `prefix` option automatically prepends a string to API keys, useful when your API expects formats like `"Bearer abc123"` or `"Token abc123"`. + -// All token management happens automatically -await client.users.list(); -``` + + -## Multiple authentication schemes +### Multiple auth schemes -You can configure endpoints to support multiple authentication schemes or combinations of schemes. In the `security` section, multiple security requirement objects (top-level list items) are treated as OR options, while multiple schemes within a single object are combined with AND. +Configure endpoints to support multiple authentication schemes or combinations. In the `security` section, multiple top-level items are OR options, while schemes within a single item are combined with AND. ```yaml title="openapi.yml" components: securitySchemes: - bearerAuth: + bearerAuth: # User-defined scheme name type: http scheme: bearer - basicAuth: + basicAuth: # User-defined scheme name type: http scheme: basic - apiKey: + apiKey: # User-defined scheme name type: apiKey in: header name: X-API-Key -/plant/search/status: - get: - summary: Search plants by status - security: - - bearerAuth: [] # Option 1: Bearer token only (OR) - - basicAuth: [] # Option 2: Basic auth AND API key (combined) - apiKey: [] + +paths: + /plant/search/status: + get: + summary: Search plants by status + security: + - bearerAuth: [] # Option 1: Bearer token only + - basicAuth: [] # Option 2: Basic auth AND API key + apiKey: [] ``` In this example, users can authenticate with either a bearer token OR with both basic auth and an API key together. -When using [OAuth client credentials](#oauth-client-credentials) with multiple authentication schemes, ensure the scheme name in your OpenAPI spec's `security` section matches the name defined in your `generators.yml` auth-schemes configuration. +When using OAuth client credentials with multiple schemes, ensure the scheme name in your OpenAPI spec's `security` section matches the name defined in `generators.yml`. -## Set default authentication in generators.yml +## Customize or override authentication in `generators.yml` -You can use `generators.yml` to define authentication schemes and set a default for all endpoints. This approach lets you customize SDK parameter names, environment variables, and is required for OAuth configuration. - -Authentication in `generators.yml` is configured in two steps: - -1. **Define your scheme** in `auth-schemes` -2. **Apply it as the default** with `api.auth` +Define your scheme in [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes), then apply it as the default across all generated SDKs with [`api.auth`](/learn/sdks/reference/generators-yml#auth): ```yml title="generators.yml" -# Step 1: Define your authentication scheme +# Define the scheme auth-schemes: - BearerAuth: + BearerAuth: # User-defined scheme name scheme: bearer token: - name: apiKey # Custom parameter name in the SDK - env: PLANTSTORE_API_KEY # Environment variable to auto-scan + name: apiKey + env: PLANTSTORE_API_KEY -# Step 2: Apply it as the default for all endpoints +# Apply it as the default across all generated SDKs api: auth: BearerAuth specs: - openapi: ./openapi.yml ``` + +For complete configuration options, see the [`auth-schemes` reference](/learn/sdks/reference/generators-yml#auth-schemes). You can also override authentication settings [for a specific SDK](/learn/sdks/reference/generators-yml#override-api-authentication-settings). + -With this configuration, all generated SDKs will require authentication: +Generated SDK usage: -```ts +```ts index.ts // Uses process.env.PLANTSTORE_API_KEY const client = new PlantStoreClient(); -// Or provide the API key explicitly +// Or provide explicitly const client = new PlantStoreClient({ apiKey: "your-api-key" }); ``` - -Authentication schemes defined in `generators.yml` take precedence over schemes defined in your OpenAPI spec. For the full reference, see [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes) and [`api.auth`](/learn/sdks/reference/generators-yml#auth). - + + -### Auth scheme reference +```yaml title="generators.yml" +auth-schemes: + BearerAuth: # User-defined scheme name + scheme: bearer + token: + name: apiKey + env: MY_API_KEY +``` - - - - + +```yaml title="generators.yml" +auth-schemes: + BasicAuth: # User-defined scheme name + scheme: basic + username: + name: clientId + env: MY_CLIENT_ID + password: + name: clientSecret + env: MY_CLIENT_SECRET +``` + - - + + +```yaml title="generators.yml" +auth-schemes: + ApiKeyAuth: # User-defined scheme name + header: X-API-Key + name: apiKey + env: MY_API_KEY + prefix: "Token " +``` + - -#### get-token + +This feature is available on [Pro and Enterprise plans](https://buildwithfern.com/pricing). Contact support@buildwithfern.com to get started. + - +```yaml title="generators.yml" +auth-schemes: + OAuth: # User-defined scheme name + scheme: oauth + type: client-credentials + client-id-env: OAUTH_CLIENT_ID + client-secret-env: OAUTH_CLIENT_SECRET + get-token: + endpoint: "POST /oauth/token" + request-properties: + client-id: client_id + client-secret: client_secret + response-properties: + access-token: access_token + expires-in: expires_in + refresh-token: refresh_token + refresh-token: + endpoint: "POST /oauth/refresh" + request-properties: + refresh-token: refresh_token + response-properties: + access-token: access_token + expires-in: expires_in +``` -#### refresh-token +Generated SDK usage: - - - +```ts index.ts +// Uses process.env.OAUTH_CLIENT_ID and process.env.OAUTH_CLIENT_SECRET +let client = new Client(); + +// Or provide credentials explicitly +client = new Client({ + clientId: "your_client_id", + clientSecret: "your_client_secret" +}) +// Token management happens automatically +await client.users.list(); +``` + +The `endpoint` values reference paths in your OpenAPI spec. When `expires-in` is returned, the SDK automatically refreshes tokens before they expire. + + + \ No newline at end of file diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 6ab903743..40a785e72 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -55,17 +55,9 @@ groups: ## `auth-schemes` -Define authentication methods for your API that your endpoints can reference. Authentication schemes defined in `generators.yml` take precedence over authentication schemes defined in your spec. +Define authentication methods for your API 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). -Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication. - - - After defining an authentication scheme, use [`api.auth`](#auth) to apply it as the default for all endpoints. - - - - Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings). - +After defining an authentication scheme, you must use [`api.auth`](#auth) to apply it as the default across all generated SDKs. Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings) if you need different auth behavior per language. ```yaml title="generators.yml" maxLines=10 auth-schemes: @@ -91,6 +83,9 @@ auth-schemes: jwt-bearer: scheme: bearer ``` + +Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication: + @@ -137,27 +132,19 @@ api: ``` - Sets the default authentication scheme for all endpoints. The value must reference a scheme name defined in [`auth-schemes`](#auth-schemes). This overrides any security schemes defined in your OpenAPI spec. + Sets the default authentication scheme for all endpoints. The value must reference a scheme name defined in [`auth-schemes`](#auth-schemes). This overrides any security schemes [defined in your OpenAPI spec](/learn/api-definitions/openapi/authentication). ```yaml title="generators.yml" - # Step 1: Define your authentication scheme - auth-schemes: - BearerAuth: - scheme: bearer - token: - name: apiKey - env: PLANTSTORE_API_KEY - - # Step 2: Apply it as the default for all endpoints + # Apply it as the default for all endpoints api: - auth: BearerAuth + auth: BearerAuth # Defined in auth-schemes specs: - openapi: ./openapi.yml ``` With this configuration, all generated SDKs will require authentication using the `BearerAuth` scheme: - ```ts + ```ts index.ts // Uses process.env.PLANTSTORE_API_KEY const client = new PlantStoreClient(); @@ -166,8 +153,9 @@ api: apiKey: "your-api-key" }); ``` - - You can also override authentication for individual generators using the [generator-level `api.auth`](#override-api-authentication-settings) setting. + + You can also override authentication for individual generators using the [generator-level `api.auth`](#override-api-authentication-settings) setting. + @@ -968,14 +956,14 @@ groups: The path to the generated snippets file. -#### Override API authentication settings +#### Override API authentication settings -Override authentication settings in your API spec for a specific SDK using the `api` configuration. +Override authentication settings for a specific SDK using the `api` configuration. -Reference a pre-defined authentication scheme by name. +Reference a [pre-defined authentication scheme](#auth-schemes) by name. ```yml title="generators.yml" {6-7} groups: From bba93261480122d245d09382d2e1ee47fcf145da Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 22:10:37 +0000 Subject: [PATCH 4/5] docs: clarify auth applies to SDKs, docs, and API Explorer - Update OpenAPI auth page intro to clarify auth applies across all Fern products - Update API Explorer page to mention generators.yml auth configuration - Add cross-references between pages Co-Authored-By: kenny@buildwithfern.com --- fern/products/api-def/openapi-pages/auth.mdx | 11 ++++++----- .../docs/pages/api-references/api-explorer.mdx | 6 +++++- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index 0355873e6..1462216c4 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -3,15 +3,15 @@ title: Authentication description: 'Model auth schemes such as bearer, basic, api key, and OAuth.' --- -Fern supports two ways to configure authentication for your API: +Fern supports two ways to configure authentication for your API. Your authentication configuration applies across all Fern products: generated SDKs, API Reference documentation, and the [API Explorer](/learn/docs/api-references/api-explorer). - **In your OpenAPI spec** using `securitySchemes` — the standard approach that keeps auth configuration portable and works with other OpenAPI tools. -- **In `generators.yml`** using `auth-schemes` — use this to customize SDK parameter names and environment variables, override what's defined in your spec, or configure OAuth (which isn't available in OpenAPI). +- **In `generators.yml`** using `auth-schemes` — use this to customize parameter names and environment variables, override what's defined in your spec, or configure OAuth (which isn't available in OpenAPI). -If you define the same scheme in both places, `generators.yml` takes precedence. This is useful when your spec is auto-generated or you want SDK behavior to differ from your spec. +If you define the same scheme in both places, `generators.yml` takes precedence. This is useful when your spec is auto-generated or you want different behavior than what's in your spec. -All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials. Authentication schemes are also automatically supported in the [API Explorer](/learn/docs/api-references/api-explorer/overview#authentication). +All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials. The [API Explorer](/learn/docs/api-references/api-explorer) automatically supports all configured authentication schemes, including [multiple schemes](#multiple-auth-schemes). ## Configure authentication in your spec @@ -332,4 +332,5 @@ await client.users.list(); The `endpoint` values reference paths in your OpenAPI spec. When `expires-in` is returned, the SDK automatically refreshes tokens before they expire. - \ No newline at end of file + + diff --git a/fern/products/docs/pages/api-references/api-explorer.mdx b/fern/products/docs/pages/api-references/api-explorer.mdx index 019658fce..83d754345 100644 --- a/fern/products/docs/pages/api-references/api-explorer.mdx +++ b/fern/products/docs/pages/api-references/api-explorer.mdx @@ -12,10 +12,14 @@ Fern will automatically populate the fields of the endpoint with the values set ## Authentication -The API Explorer supports all authentication schemes configured in your OpenAPI spec, including [multiple authentication schemes](/learn/api-definitions/openapi/authentication#multiple-authentication-schemes). When multiple schemes are available, the API Explorer automatically displays them in a dropdown menu, allowing users to select and configure their preferred authentication method before sending requests. +The API Explorer supports all authentication schemes configured in your OpenAPI spec or in `generators.yml`, including [multiple authentication schemes](/learn/api-definitions/openapi/authentication#multiple-auth-schemes). When multiple schemes are available, the API Explorer automatically displays them in a dropdown menu, allowing users to select and configure their preferred authentication method before sending requests. Once a user sets their authentication credentials, their credentials persist throughout their entire exploration session. + +You can configure authentication in your OpenAPI spec using `securitySchemes`, or in `generators.yml` using `auth-schemes` for more customization options. See [Authentication](/learn/api-definitions/openapi/authentication) for details. + +
From 190f33491f7a5bb1b78b96105839131191874575 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 4 Feb 2026 18:23:19 -0500 Subject: [PATCH 5/5] update language --- fern/products/api-def/openapi-pages/auth.mdx | 106 ++++-------------- .../pages/api-references/api-explorer.mdx | 6 +- .../reference/generators-yml-reference.mdx | 4 +- 3 files changed, 22 insertions(+), 94 deletions(-) diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index 1462216c4..2532449eb 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -3,16 +3,12 @@ title: Authentication description: 'Model auth schemes such as bearer, basic, api key, and OAuth.' --- -Fern supports two ways to configure authentication for your API. Your authentication configuration applies across all Fern products: generated SDKs, API Reference documentation, and the [API Explorer](/learn/docs/api-references/api-explorer). +Fern supports two ways to configure authentication: - **In your OpenAPI spec** using `securitySchemes` — the standard approach that keeps auth configuration portable and works with other OpenAPI tools. - **In `generators.yml`** using `auth-schemes` — use this to customize parameter names and environment variables, override what's defined in your spec, or configure OAuth (which isn't available in OpenAPI). -If you define the same scheme in both places, `generators.yml` takes precedence. This is useful when your spec is auto-generated or you want different behavior than what's in your spec. - - -All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials. The [API Explorer](/learn/docs/api-references/api-explorer) automatically supports all configured authentication schemes, including [multiple schemes](#multiple-auth-schemes). - +Your authentication configuration applies across generated SDKs and the [API Explorer](/learn/docs/api-references/api-explorer). All SDKs support both direct configuration and environment variables for credentials. If you define the same scheme in both places, `generators.yml` takes precedence. ## Configure authentication in your spec @@ -31,6 +27,14 @@ security: - BearerAuth: [] ``` +Generated SDK usage: + +```ts index.ts +const client = new Client({ + token: "ey34..." +}); +``` + @@ -42,14 +46,6 @@ components: scheme: bearer ``` -Generated SDK usage: - -```ts index.ts -const client = new Client({ - token: "ey34..." -}) -``` - To customize parameter names and environment variables, add `x-fern-bearer`: ```yaml title="openapi.yml" @@ -58,21 +54,11 @@ components: BearerAuth: type: http scheme: bearer - x-fern-bearer: + x-fern-bearer: name: apiKey env: PLANTSTORE_API_KEY ``` -```ts index.ts -// Uses process.env.PLANTSTORE_API_KEY -let client = new Client(); - -// Parameter renamed from 'token' to 'apiKey' -client = new Client({ - apiKey: "ey34..." -}) -``` - @@ -84,21 +70,12 @@ components: scheme: basic ``` -Generated SDK usage: - -```ts index.ts -const client = new Client({ - username: "joeschmoe", - password: "ey34..." -}) -``` - To customize parameter names and environment variables, add `x-fern-basic`: ```yaml title="openapi.yml" components: securitySchemes: - BasicAuth: + BasicAuth: type: http scheme: basic x-fern-basic: @@ -110,43 +87,24 @@ components: env: PLANTSTORE_CLIENT_SECRET ``` -```ts index.ts -// Uses process.env.PLANTSTORE_CLIENT_ID and process.env.PLANTSTORE_CLIENT_SECRET -let client = new Client(); - -// Parameters renamed -client = new Client({ - clientId: "joeschmoe", - clientSecret: "ey34..." -}) -``` - ```yml title="openapi.yml" -components: - securitySchemes: +components: + securitySchemes: ApiKeyAuth: # User-defined scheme name type: apiKey in: header name: X_API_KEY ``` -Generated SDK usage: - -```ts index.ts -const client = new Client({ - apiKey: "ey34..." -}) -``` - To customize parameter names and environment variables, add `x-fern-header`: ```yaml title="openapi.yml" -components: - securitySchemes: - ApiKeyAuth: +components: + securitySchemes: + ApiKeyAuth: type: apiKey in: header name: X_API_KEY @@ -156,16 +114,6 @@ components: prefix: "Token " ``` -```ts index.ts -// Uses process.env.PLANTSTORE_API_KEY -let client = new Client(); - -// Parameter renamed from 'apiKey' to 'apiToken' -client = new Client({ - apiToken: "ey34..." -}) -``` - The `prefix` option automatically prepends a string to API keys, useful when your API expects formats like `"Bearer abc123"` or `"Token abc123"`. @@ -209,7 +157,7 @@ When using OAuth client credentials with multiple schemes, ensure the scheme nam ## Customize or override authentication in `generators.yml` -Define your scheme in [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes), then apply it as the default across all generated SDKs with [`api.auth`](/learn/sdks/reference/generators-yml#auth): +Define your scheme in [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes), then apply it as the default across all endpoints with [`api.auth`](/learn/sdks/reference/generators-yml#auth): ```yml title="generators.yml" # Define the scheme @@ -220,7 +168,7 @@ auth-schemes: name: apiKey env: PLANTSTORE_API_KEY -# Apply it as the default across all generated SDKs +# Apply it as the default across all endpoints api: auth: BearerAuth specs: @@ -313,22 +261,6 @@ auth-schemes: expires-in: expires_in ``` -Generated SDK usage: - -```ts index.ts -// Uses process.env.OAUTH_CLIENT_ID and process.env.OAUTH_CLIENT_SECRET -let client = new Client(); - -// Or provide credentials explicitly -client = new Client({ - clientId: "your_client_id", - clientSecret: "your_client_secret" -}) - -// Token management happens automatically -await client.users.list(); -``` - The `endpoint` values reference paths in your OpenAPI spec. When `expires-in` is returned, the SDK automatically refreshes tokens before they expire. diff --git a/fern/products/docs/pages/api-references/api-explorer.mdx b/fern/products/docs/pages/api-references/api-explorer.mdx index 83d754345..0c95d603c 100644 --- a/fern/products/docs/pages/api-references/api-explorer.mdx +++ b/fern/products/docs/pages/api-references/api-explorer.mdx @@ -12,14 +12,10 @@ Fern will automatically populate the fields of the endpoint with the values set ## Authentication -The API Explorer supports all authentication schemes configured in your OpenAPI spec or in `generators.yml`, including [multiple authentication schemes](/learn/api-definitions/openapi/authentication#multiple-auth-schemes). When multiple schemes are available, the API Explorer automatically displays them in a dropdown menu, allowing users to select and configure their preferred authentication method before sending requests. +The API Explorer supports [all authentication schemes](/learn/api-definitions/openapi/authentication) configured in your OpenAPI spec or in `generators.yml`, including multiple authentication schemes. When multiple schemes are available, the API Explorer automatically displays them in a dropdown menu, allowing users to select and configure their preferred authentication method before sending requests. Once a user sets their authentication credentials, their credentials persist throughout their entire exploration session. - -You can configure authentication in your OpenAPI spec using `securitySchemes`, or in `generators.yml` using `auth-schemes` for more customization options. See [Authentication](/learn/api-definitions/openapi/authentication) for details. - -
diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 40a785e72..fcc64326a 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -55,9 +55,9 @@ groups: ## `auth-schemes` -Define authentication methods for your API 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). +Define authentication methods for your SDKs and the [API Explorer](/learn/docs/api-references/api-explorer/overview) 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 generated SDKs. Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings) if you need different auth behavior per language. +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. ```yaml title="generators.yml" maxLines=10 auth-schemes: