diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx
index f2cfa9fbc..c6bc370ab 100644
--- a/fern/products/sdks/reference/generators-yml-reference.mdx
+++ b/fern/products/sdks/reference/generators-yml-reference.mdx
@@ -59,7 +59,7 @@ groups:
## auth-schemes
Define authentication methods for your API. Create named authentication schemes that your endpoints can reference.
-Choose from OAuth 2.0, custom headers (API keys), HTTP Basic, or Bearer token authentication.
+Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication.
```yaml
auth-schemes:
@@ -86,244 +86,29 @@ auth-schemes:
scheme: bearer
```
-### OAuth Authentication
-
-Configure OAuth 2.0 client credentials authentication.
-
-```yaml
-auth-schemes:
- my-oauth: # User-defined scheme name
- scheme: oauth
- type: client-credentials
- scopes:
- - "read:users"
- - "write:users"
- client-id-env: "OAUTH_CLIENT_ID"
- client-secret-env: "OAUTH_CLIENT_SECRET"
- 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"
-```
-
-
- Must be set to `"oauth"` for OAuth authentication schemes.
-
-
- The OAuth flow type. Currently only `"client-credentials"` is supported.
-
-
- List of OAuth scopes to request during authentication.
-
-
- Environment variable name containing the OAuth client ID.
-
-
- Environment variable name containing the OAuth client secret.
-
-
- Sets the token header value prefix.
-
-
- Sets the token header key name.
-
-
-#### get-token
-
-Configuration for the token acquisition endpoint.
-
-```yaml
-auth-schemes:
- my-oauth:
- scheme: oauth
- # ... other OAuth config
- get-token:
- endpoint: "auth.get_token"
- request-properties:
- client-id: "clientId"
- client-secret: "clientSecret"
- response-properties:
- access-token: "access_token"
- expires-in: "expires_in"
-```
-
-
- The endpoint to get the access token, such as `'auth.get_token'`.
-
-
- Customizes the property names used in the token request.
-
-
- The property name for the client ID in the request.
-
-
- The property name for the client secret in the request.
-
-
- The property name for the scopes in the request.
-
-
- Maps custom property names in your OAuth token response (e.g., if your API returns `accessToken` instead of `access_token`).
-
-
- The property name for the access token in the response.
-
-
- The property name for the expires in property in the response.
-
-
- The property name for the refresh token in the response.
-
-
-#### refresh-token
-
-Configuration for the token refresh endpoint.
-
-```yaml
-auth-schemes:
- my-oauth:
- scheme: oauth
- # ... other OAuth config
- refresh-token:
- endpoint: "auth.refresh_token"
- request-properties:
- refresh-token: "refreshToken"
- response-properties:
- access-token: "access_token"
- expires-in: "expires_in"
-```
-
-
- The endpoint to refresh the access token, such as `'auth.refresh_token'`.
-
-
- Maps custom property names in your refresh token request.
-
-
- The property name for the refresh token in the request.
-
-
- Maps custom property names in your refresh token response.
-
-
- The property name for the access token in the response.
-
-
- The property name for the expires in property in the response.
-
-
- The property name for the refresh token in the response.
-
-
### 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"
-```
+### Basic Authentication
-
- The name of the HTTP header to use for authentication.
-
-
- A descriptive name for this authentication scheme.
-
-
- The type of the header value.
-
-
- A prefix to prepend to the header value (e.g., `"Bearer "` or `"Token "`).
-
-
- Environment variable name containing the authentication value.
-
+
-### Basic Authentication
+### Bearer Token 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"
- password:
- name: "Password"
- env: "BASIC_AUTH_PASSWORD"
-```
+### OAuth Authentication
-
- Must be set to `"basic"` for Basic authentication schemes.
-
-
- Configuration for the username credential.
-
-
- A descriptive name for the username.
-
-
- Environment variable name containing the username.
-
-
- Configuration for the password credential.
-
-
- A descriptive name for the password.
-
-
- Environment variable name containing the password.
-
+
-### Bearer Token Authentication
+#### get-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"
-```
+#### refresh-token
-
- Must be set to `"bearer"` for Bearer token authentication schemes.
-
-
- Configuration for the bearer token.
-
-
- A descriptive name for the token.
-
-
- Environment variable name containing the bearer token.
-
+
## api
@@ -595,30 +380,26 @@ api:
## whitelabel
-Branding/publishing configuration (like GitHub credentials for publishing).
+
+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.
```yaml
whitelabel:
github:
- username: "my-github-username"
+ username: "company-github-username"
email: "my-email@example.com"
token: "ghp_xxxxxxxxxxxx"
-```
-
+
+ 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.
-
-
+
+ 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.
-
-
-
-
-
+
+ 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.
@@ -633,19 +414,19 @@ metadata:
email: "jane@example.com"
```
-
-
-
-
+
+ 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.
-
+
+ The full name of the author to be credited in the SDK package metadata.
-
+
+ The email address of the author. This will be included in package metadata and may be used by package managers for contact information.
## readme
@@ -1109,13 +890,13 @@ groups:
The path to the generated snippets file.
-### API Settings Override
+### 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.
-#### String Reference
+#### Single Authentication Scheme
Reference a pre-defined authentication scheme by name.
@@ -1129,37 +910,13 @@ groups:
auth: "bearer-token"
```
-
-The name of an authentication scheme defined in your API specification.
-
-
-#### Scheme Reference
-
-Reference a specific authentication scheme with optional documentation.
-
-```yml {6-9}
-groups:
- ts-sdk:
- generators:
- - name: fernapi/fern-typescript-sdk
- ...
- api:
- auth:
- scheme: "my-auth-scheme"
- docs: "Custom authentication method"
-```
-
-
-The name of the authentication scheme to use.
-
-
-
-Documentation describing this authentication configuration.
+
+The authentication scheme to use. Can be either a string reference (`"bearer-token"`) or scheme object (`scheme: "bearer-token"`).
#### Multiple Authentication Options
-Allow any of multiple authentication schemes to be used.
+Allow users to authenticate with any of several methods:
```yml {6-12}
groups:
@@ -1173,96 +930,17 @@ groups:
- "api-key"
- "bearer-token"
- scheme: "oauth-flow"
- docs: "Supports multiple authentication methods"
```
-List of authentication schemes where any one can be used. Can include string references or scheme objects.
+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"`).
-
-Documentation describing this authentication configuration.
-
#### 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`).
-
-
-
-Send authentication tokens or API keys in custom HTTP headers.
-
-```yml {8-12}
-groups:
- ts-sdk:
- generators:
- - name: fernapi/fern-typescript-sdk
- ...
- api:
- auth-schemes:
- api-key: # User-defined name for your auth schema
- header: "X-API-Key"
- type: "string"
- prefix: "Bearer "
- env: "API_KEY"
-```
-
-
-The name of the header to send the authentication value in.
-
-
-
-The type of the authentication value. Defaults to "string".
-
-
-
-A prefix to add before the authentication value in the header.
-
-
-
-Environment variable name to read the authentication value from.
-
-
-
-
-
-Standard HTTP basic authentication using username and password credentials.
-
-```yaml {8-15}
-groups:
- ts-sdk:
- generators:
- - name: fernapi/fern-typescript-sdk
- ...
- api:
- auth-schemes:
- basic-auth: # User-defined name for your auth schema
- scheme: "basic"
- username:
- name: "username"
- env: "AUTH_USERNAME"
- password:
- name: "password"
- env: "AUTH_PASSWORD"
-```
-
-Must be set to "basic" for basic authentication.
-
-
-
-Configuration for the username field.
-
-
-
-Configuration for the password field.
-
-
-
-
-
-Authentication using bearer tokens in the Authorization header.
-
```yml {8-12}
groups:
ts-sdk:
@@ -1278,69 +956,35 @@ groups:
env: "BEARER_TOKEN"
```
-
-Must be set to "bearer" for bearer token authentication.
-
+
+
-
-Configuration for the bearer token.
-
+
-
+
-OAuth 2.0 client credentials flow for machine-to-machine authentication.
+
-```yml {8-12}
-groups:
- ts-sdk:
- generators:
- - name: fernapi/fern-typescript-sdk
- ...
- api:
- auth-schemes:
- oauth: # User-defined name for your auth schema
- scheme: "oauth"
- type: "client-credentials"
- get-token:
- endpoint: "auth.get_token"
-```
+
-
-Must be set to "oauth" for OAuth authentication.
-
+
-
-Must be set to "client-credentials" for OAuth client credentials flow.
-
+
+
-
-List of OAuth scopes to request.
-
+
-
-Environment variable name for the OAuth client ID.
-
+
-
-Environment variable name for the OAuth client secret.
-
+##### get-token
-
-Sets the token header value prefix. Defaults to 'Bearer'.
-
+
-
-Sets the token header key name. Defaults to 'Authorization'.
-
+##### refresh-token
-
-Configuration for the token endpoint to get access tokens.
-
+
-
-Configuration for the refresh token endpoint.
-
diff --git a/fern/products/sdks/snippets/basic-auth-params.mdx b/fern/products/sdks/snippets/basic-auth-params.mdx
new file mode 100644
index 000000000..e97917c0e
--- /dev/null
+++ b/fern/products/sdks/snippets/basic-auth-params.mdx
@@ -0,0 +1,35 @@
+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"
+ password:
+ name: "Password"
+ env: "BASIC_AUTH_PASSWORD"
+```
+
+
+ Must be set to `"basic"` for Basic authentication schemes.
+
+
+ Configuration for the username credential.
+
+
+ A descriptive name for the username.
+
+
+ Environment variable name containing the username.
+
+
+ Configuration for the password credential.
+
+
+ A descriptive name for the password.
+
+
+ Environment variable name containing the password.
+
\ No newline at end of file
diff --git a/fern/products/sdks/snippets/bearer-auth-params.mdx b/fern/products/sdks/snippets/bearer-auth-params.mdx
new file mode 100644
index 000000000..42289dd0e
--- /dev/null
+++ b/fern/products/sdks/snippets/bearer-auth-params.mdx
@@ -0,0 +1,23 @@
+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"
+```
+
+
+ Must be set to `"bearer"` for Bearer token authentication schemes.
+
+
+ Configuration for the bearer token.
+
+
+ A descriptive name for the token.
+
+
+ Environment variable name containing the bearer token.
+
\ No newline at end of file
diff --git a/fern/products/sdks/snippets/header-auth-params.mdx b/fern/products/sdks/snippets/header-auth-params.mdx
new file mode 100644
index 000000000..53fef8c70
--- /dev/null
+++ b/fern/products/sdks/snippets/header-auth-params.mdx
@@ -0,0 +1,27 @@
+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"
+```
+
+
+ The name of the HTTP header to use for authentication.
+
+
+ A descriptive name for this authentication scheme.
+
+
+ The type of the header value.
+
+
+ A prefix to prepend to the header value (e.g., `"Bearer "` or `"Token "`).
+
+
+ Environment variable name containing the authentication value.
+
\ No newline at end of file
diff --git a/fern/products/sdks/snippets/oauth-get-token.mdx b/fern/products/sdks/snippets/oauth-get-token.mdx
new file mode 100644
index 000000000..938bf9569
--- /dev/null
+++ b/fern/products/sdks/snippets/oauth-get-token.mdx
@@ -0,0 +1,40 @@
+Configuration for the token acquisition endpoint.
+
+```yaml
+get-token:
+ endpoint: "auth.get_token"
+ request-properties:
+ client-id: "clientId"
+ client-secret: "clientSecret"
+ response-properties:
+ access-token: "access_token"
+ expires-in: "expires_in"
+```
+
+
+ The endpoint to get the access token, such as `'auth.get_token'`.
+
+
+ Customizes the property names used in the token request.
+
+
+ The property name for the client ID in the request.
+
+
+ The property name for the client secret in the request.
+
+
+ The property name for the scopes in the request.
+
+
+ Maps custom property names in your OAuth token response (e.g., if your API returns `accessToken` instead of `access_token`).
+
+
+ The property name for the access token in the response.
+
+
+ The property name for the expires in property in the response.
+
+
+ The property name for the refresh token in the response.
+
\ No newline at end of file
diff --git a/fern/products/sdks/snippets/oauth-params.mdx b/fern/products/sdks/snippets/oauth-params.mdx
new file mode 100644
index 000000000..b605e92f7
--- /dev/null
+++ b/fern/products/sdks/snippets/oauth-params.mdx
@@ -0,0 +1,55 @@
+Configure OAuth 2.0 client credentials authentication.
+
+```yaml
+auth-schemes:
+ my-oauth: # User-defined scheme name
+ scheme: oauth
+ type: client-credentials
+ scopes:
+ - "read:users"
+ - "write:users"
+ client-id-env: "OAUTH_CLIENT_ID"
+ client-secret-env: "OAUTH_CLIENT_SECRET"
+ 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"
+```
+
+
+ Must be set to `"oauth"` for OAuth authentication schemes.
+
+
+ The OAuth flow type. Currently only `"client-credentials"` is supported.
+
+
+ List of OAuth scopes to request during authentication.
+
+
+ Environment variable name containing the OAuth client ID.
+
+
+ Environment variable name containing the OAuth client secret.
+
+
+ Sets the token header value prefix.
+
+
+ Sets the token header key name.
+
\ 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
new file mode 100644
index 000000000..cf992a5ef
--- /dev/null
+++ b/fern/products/sdks/snippets/oauth-refresh-token.mdx
@@ -0,0 +1,33 @@
+Configuration for the token refresh endpoint.
+
+```yaml
+refresh-token:
+ endpoint: "auth.refresh_token"
+ request-properties:
+ refresh-token: "refreshToken"
+ response-properties:
+ access-token: "access_token"
+ expires-in: "expires_in"
+```
+
+
+ The endpoint to refresh the access token, such as `'auth.refresh_token'`.
+
+
+ Maps custom property names in your refresh token request.
+
+
+ The property name for the refresh token in the request.
+
+
+ Maps custom property names in your refresh token response.
+
+
+ The property name for the access token in the response.
+
+
+ The property name for the expires in property in the response.
+
+
+ The property name for the refresh token in the response.
+
\ No newline at end of file