OpenAPI

Authentication

Model auth schemes such as bearer, basic, and api key.

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

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:

openapi.yml
1components: 
2  securitySchemes: 
3    BearerAuth:
4      type: http
5      scheme: bearer  
6    ApiKey: 
7      type: apiKey
8      in: header
9      name: X_API_KEY

Override security scheme

You can use generators.yml to define custom authentication schemes that will take precedence when generating SDKs.

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