OpenAPI

Authentication

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.

openapi.yml
1components: 
2  securitySchemes: 
3    ...

To apply a security scheme across all endpoints, reference the securityScheme within the security section of your OpenAPI Specification.

openapi.yml
1components: 
2  securitySchemes: 
3    AuthScheme:
4      ...
5security: 
6  - AuthScheme: []

Bearer security scheme

Start by defining a bearer security scheme in your openapi.yml:

openapi.yml
1components:
2  securitySchemes:
3    BearerAuth:
4      type: http
5      scheme: bearer

This will generate an SDK where the user would have to provide a mandatory argument called token.

index.ts
1const client = new Client({
2  token: "ey34..."
3})

If you want to control variable naming and the environment variable to scan, use the configuration below:

openapi.yml
1components:
2  securitySchemes:
3    BearerAuth:
4      type: http
5      scheme: bearer
6      x-fern-bearer: 
7        name: apiKey
8        env: PLANTSTORE_API_KEY

The generated SDK would look like:

index.ts
1// Uses process.env.PLANTSTORE_API_KEY
2let client = new Client(); 
3
4// token has been renamed to apiKey
5client = new Client({
6  apiKey: "ey34..."
7})

Basic security scheme

Start by defining a basic security scheme in your openapi.yml:

openapi.yml
1components:
2  securitySchemes:
3    BasicAuth:
4      type: http
5      scheme: basic

This will generate an SDK where the user would have to provide a mandatory arguments called username and password.

index.ts
1const client = new Client({
2  username: "joeschmoe"
3  password: "ey34..."
4})

If you want to control variable naming and environment variables to scan, use the configuration below:

openapi.yml
1components:
2  securitySchemes:
3    BasicAuth:
4      type: http
5      scheme: basic
6      x-fern-basic:
7        username:
8          name: clientId
9          env: PLANTSTORE_CLIENT_ID
10        password:
11          name: clientSecret
12          env: PLANTSTORE_CLIENT_SECRET

The generated SDK would look like:

index.ts
1// Uses process.env.PLANTSTORE_CLIENT_ID and process.env.PLANTSTORE_CLIENT_SECRET
2let client = new Client(); 
3
4// parameters have been renamed
5client = new Client({
6  clientId: "joeschmoe", 
7  clientSecret: "ey34..."
8})

ApiKey security scheme

Start by defining an apiKey security scheme in your openapi.yml:

openapi.yml
1components: 
2  securitySchemes: 
3    ApiKey: 
4      type: apiKey
5      in: header
6      name: X_API_KEY

This will generate an SDK where the user would have to provide a mandatory argument called apiKey.

index.ts
1const client = new Client({
2  apiKey: "ey34..."
3})

If you want to control variable naming and environment variables to scan, use the configuration below:

openapi.yml
1components: 
2  securitySchemes: 
3    ApiKey: 
4      type: apiKey
5      in: header
6      name: X_API_KEY
7      x-fern-header:
8        name: apiToken
9        env: PLANTSTORE_API_KEY
10        prefix: "Token " # Optional

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:

index.ts
1// Uses process.env.PLANTSTORE_API_KEY
2let client = new Client(); 
3
4// parameters have been renamed
5client = new Client({
6  apiToken: "ey34..."
7})

OAuth client credentials

Pro and Enterprise feature

This feature is available only for the Pro and Enterprise plans. To get started, reach out to support@buildwithfern.com.

Configure OAuth 2.0 client credentials in generators.yml rather than in the API specification:

generators.yml
1auth-schemes:
2  OAuth:
3    scheme: oauth
4    type: client-credentials
5    client-id-env: "OAUTH_CLIENT_ID"
6    client-secret-env: "OAUTH_CLIENT_SECRET"
7    get-token:
8      endpoint: "POST /oauth/token"
9      request-properties:
10        client-id: "client_id"
11        client-secret: "client_secret"
12      response-properties:
13        access-token: "access_token"
14        expires-in: "expires_in"
15        refresh-token: "refresh_token"
16    refresh-token:
17      endpoint: "POST /oauth/refresh"
18      request-properties:
19        refresh-token: "refresh_token"
20      response-properties:
21        access-token: "access_token"
22        expires-in: "expires_in"
23api:
24  auth: OAuth
Endpoint configuration and token refresh

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

The generated SDK would look like:

index.ts
1// Uses process.env.OAUTH_CLIENT_ID and process.env.OAUTH_CLIENT_SECRET
2let client = new Client(); 
3
4// Or provide credentials explicitly
5client = new Client({
6  clientId: "your_client_id",
7  clientSecret: "your_client_secret"
8})
9
10// All token management happens automatically
11await client.users.list();

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.

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.

generators.yml
1auth-schemes:                 # Define custom auth scheme
2  Bearer:                     
3    scheme: bearer
4    token:
5      name: apiKey             # Custom parameter name in the SDK
6      env: YOUR_TOKEN_NAME     # Environment variable to auto-scan
7api:
8  auth: Bearer # Apply the custom scheme, overriding the OpenAPI spec

Auth scheme reference

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.

For Fern Definition, you can configure OAuth authentication either in generators.yml or directly in your api.yml file. For OpenAPI, OAuth must be configured in generators.yml.

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

generators.yml
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
'client-credentials'Required

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

scopes
list of strings

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

client-id-env
string

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

client-secret-env
string

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

token-prefix
stringDefaults to Bearer

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

token-header
stringDefaults to Authorization

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

get-token

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

generators.yml
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 that issues access tokens, such as 'auth.get_token'.

request-properties
object

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

request-properties.client-id
string

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

request-properties.client-secret
string

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

request-properties.scopes
string

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

response-properties
object

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

response-properties.access-token
string

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

response-properties.expires-in
string

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

refresh-token
string

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

refresh-token

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

generators.yml
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 that refreshes access tokens (e.g., "POST /oauth/refresh" or "auth.refreshToken").

request-properties
object

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

request-properties.refresh-token
stringRequired

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

response-properties
object

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

response-properties.access-token
string

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

response-properties.expires-in
string

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

response-properties.refresh-token
string

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