From 268d4202233534e30d704e780beb0fd2b912ca7a Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 15 Oct 2025 16:13:08 -0400 Subject: [PATCH 1/3] expand and clarify oauth options --- fern/products/api-def/openapi-pages/auth.mdx | 69 +++++++++++++++++-- fern/products/sdks/capabilities.mdx | 2 +- .../reference/generators-yml-reference.mdx | 2 +- .../sdks/snippets/oauth-get-token.mdx | 32 ++++----- fern/products/sdks/snippets/oauth-params.mdx | 21 +++--- .../sdks/snippets/oauth-refresh-token.mdx | 26 +++---- 6 files changed, 105 insertions(+), 47 deletions(-) diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index 22af42ae..ff291007 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -1,6 +1,7 @@ --- title: Authentication -subtitle: Model auth schemes such as bearer, basic, and api key. +description: Model auth schemes such as bearer, basic, api key, and OAuth. +max-toc-depth: 2 --- Configuring authentication schemes happens in the `components.securitySchemes` section of OpenAPI. All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials. @@ -181,6 +182,60 @@ client = new Client({ }) ``` +## OAuth client credentials + + + +Configure OAuth 2.0 using client credentials in `generators.yml`: + +```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](#oauth-authentication) 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" +}) + +// All token management happens automatically +await client.users.list(); +``` + ## Multiple security schemes If you would like to define multiple security schemes, simply @@ -201,11 +256,11 @@ components: ## Override security scheme -You can use `generators.yml` to define custom authentication schemes that will take precedence when generating SDKs. +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. 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. -```yml title="generators.yml" {1-6, 8} +```yml title="generators.yml" auth-schemes: # Define custom auth scheme Bearer: scheme: bearer @@ -219,16 +274,16 @@ api: ### Auth scheme reference - + - + - + - + #### get-token diff --git a/fern/products/sdks/capabilities.mdx b/fern/products/sdks/capabilities.mdx index 749baabb..207ce797 100644 --- a/fern/products/sdks/capabilities.mdx +++ b/fern/products/sdks/capabilities.mdx @@ -93,7 +93,7 @@ layout: overview - + Fern supports OAuth as a first class citizen

diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 7bfa46d9..a5b2cd82 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -95,7 +95,7 @@ auth-schemes: - + #### `get-token` diff --git a/fern/products/sdks/snippets/oauth-get-token.mdx b/fern/products/sdks/snippets/oauth-get-token.mdx index 938bf956..b739cedc 100644 --- a/fern/products/sdks/snippets/oauth-get-token.mdx +++ b/fern/products/sdks/snippets/oauth-get-token.mdx @@ -1,6 +1,6 @@ -Configuration for the token acquisition endpoint. +Specifies the endpoint that exchanges client credentials for an access token. This endpoint is called automatically when the SDK client is initialized. -```yaml +```yaml title="generators.yml" get-token: endpoint: "auth.get_token" request-properties: @@ -12,29 +12,29 @@ get-token: ``` - The endpoint to get the access token, such as `'auth.get_token'`. + The endpoint that issues access tokens, such as `'auth.get_token'`. - Customizes the property names used in the token request. + 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`). - - The property name for the client ID in the request. + + The request field name for the client ID in your API (e.g., `"clientId"`, `"client_id"`). - - The property name for the client secret in the request. + + The request field name for the client secret in your API (e.g., `"clientSecret"`, `"client_secret"`). - - The property name for the scopes in the request. + + The request field name for scopes in your API (e.g., `"scope"`, `"scopes"`). - Maps custom property names in your OAuth token response (e.g., if your API returns `accessToken` instead of `access_token`). + 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`). - - The property name for the access token in the response. + + The response field name for the access token in your API (e.g., `"accessToken"`, `"access_token"`). - - The property name for the expires in property in the response. + + The response field name for token expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). When present, the SDK automatically refreshes tokens before expiration. - The property name for the refresh token in the response. + The response field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`). Required if using the `refresh-token` flow. \ No newline at end of file diff --git a/fern/products/sdks/snippets/oauth-params.mdx b/fern/products/sdks/snippets/oauth-params.mdx index f101392d..c19c2541 100644 --- a/fern/products/sdks/snippets/oauth-params.mdx +++ b/fern/products/sdks/snippets/oauth-params.mdx @@ -1,6 +1,10 @@ -Configure OAuth 2.0 client credentials authentication. + + For Fern Definition, you can configure OAuth authentication either in `generators.yml` or [directly in your `api.yml` file](/api-definitions/ferndef/authentication#oauth-client-credentials). For OpenAPI, [OAuth must be configured in `generators.yml`](/api-definitions/openapi/authentication#oauth-client-credentials). + -```yaml +Configure OAuth 2.0 client credentials authentication. Optionally configure a `refresh-token` endpoint for token renewal without re-authentication. + +```yaml title="generators.yml" maxLines=10 auth-schemes: my-oauth: # User-defined scheme name scheme: oauth @@ -31,15 +35,14 @@ auth-schemes: expires-in: "expires_in" refresh-token: "refresh_token" ``` - Must be set to `"oauth"` for OAuth authentication schemes. - - The OAuth flow type. Currently only `"client-credentials"` is supported. + + The OAuth 2.0 grant type. Currently only `"client-credentials"` is supported. - - List of OAuth scopes to request during authentication. + + OAuth scopes to request when obtaining access tokens (e.g., `"read:users"`, `"write:orders"`). Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization. @@ -48,8 +51,8 @@ auth-schemes: Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization. - Sets the token header value prefix. + Prefix added to the access token in the Authorization header (e.g., `"Bearer"` results in `"Authorization: Bearer "`). Useful when your API expects a custom format. - Sets the token header key name. + 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"`). \ No newline at end of file diff --git a/fern/products/sdks/snippets/oauth-refresh-token.mdx b/fern/products/sdks/snippets/oauth-refresh-token.mdx index cf992a5e..75b28c27 100644 --- a/fern/products/sdks/snippets/oauth-refresh-token.mdx +++ b/fern/products/sdks/snippets/oauth-refresh-token.mdx @@ -1,6 +1,6 @@ -Configuration for the token refresh endpoint. +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. -```yaml +```yaml title="generators.yml" refresh-token: endpoint: "auth.refresh_token" request-properties: @@ -11,23 +11,23 @@ refresh-token: ``` - The endpoint to refresh the access token, such as `'auth.refresh_token'`. + The endpoint that refreshes access tokens (e.g., `"POST /oauth/refresh"` or `"auth.refreshToken"`). - Maps custom property names in your refresh token request. + Maps OAuth parameter names to your API's request field names for the refresh flow. - - The property name for the refresh token in the request. + + The request field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`). - Maps custom property names in your refresh token response. + Maps your API's refresh response field names to OAuth standard names. - - The property name for the access token in the response. + + The response field name for the new access token (e.g., `"accessToken"`, `"access_token"`). - - The property name for the expires in property in the response. + + The response field name for the new token's expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). - - The property name for the refresh token in the response. + + The response field name if your API issues a new refresh token with each refresh (token rotation). \ No newline at end of file From ec1e475369154a0fe1f16ff816483c583fe08e50 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 16 Oct 2025 14:40:58 -0400 Subject: [PATCH 2/3] refine wording --- fern/products/api-def/openapi-pages/auth.mdx | 2 +- fern/products/sdks/reference/generators-yml-reference.mdx | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index ff291007..75eb46f4 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -186,7 +186,7 @@ client = new Client({ -Configure OAuth 2.0 using client credentials in `generators.yml`: +Configure OAuth 2.0 client credentials in `generators.yml` rather than in the API specification: ```yaml title="generators.yml" maxLines=10 auth-schemes: diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index a5b2cd82..378b4970 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -57,9 +57,13 @@ groups: ## `auth-schemes` -Define authentication methods for your API that your endpoints can reference. Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication. +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. -Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings). +Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication. + + + Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings). + ```yaml title="generators.yml" maxLines=10 auth-schemes: From 3e2883fb1d4a86a5c6a91b919aa89c05e1b5f1df Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 29 Oct 2025 11:39:10 -0400 Subject: [PATCH 3/3] remove multiple security schemes info --- fern/products/api-def/openapi-pages/auth.mdx | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index 75eb46f4..2eaa1e75 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -236,24 +236,6 @@ client = new Client({ await client.users.list(); ``` -## Multiple security schemes - -If you would like to define multiple security schemes, simply -list them under `components.securitySchemes`. For example, if you wanted to support -`basic` and `apiKey` security schemes, see the example below: - -```yaml title="openapi.yml" {3,6} -components: - securitySchemes: - BearerAuth: - type: http - scheme: bearer - ApiKey: - type: apiKey - in: header - name: X_API_KEY -``` - ## Override security scheme 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.