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.
To apply a security scheme across all endpoints, reference the securityScheme
within the security
section of your OpenAPI Specification.
Bearer security scheme
Start by defining a bearer
security scheme in your openapi.yml
:
This will generate an SDK where the user would have to provide
a mandatory argument called token
.
If you want to control variable naming and the environment variable to scan, use the configuration below:
The generated SDK would look like:
Basic security scheme
Start by defining a basic
security scheme in your openapi.yml
:
This will generate an SDK where the user would have to provide
a mandatory arguments called username
and password
.
If you want to control variable naming and environment variables to scan, use the configuration below:
The generated SDK would look like:
ApiKey security scheme
Start by defining an apiKey
security scheme in your openapi.yml
:
This will generate an SDK where the user would have to provide
a mandatory argument called apiKey
.
If you want to control variable naming and environment variables to scan, use the configuration below:
The generated SDK would look like:
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:
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.
Auth scheme reference
Header authentication
Configure authentication using custom HTTP headers, such as API keys or tokens.
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. When specified, the generated SDK will automatically scan for this environment variable at initialization.
Basic authentication
Configure HTTP Basic authentication using username and password credentials.
Must be set to "basic"
for Basic authentication schemes.
Configuration for the username credential.
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"
.
Configuration for the password credential.
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"
.
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
.
Bearer token authentication
Configure Bearer token authentication for API access.
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. When specified, the generated SDK will automatically scan for this environment variable at initialization.
OAuth authentication
Configure OAuth 2.0 client credentials authentication.
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. When specified, the generated SDK will automatically scan for this environment variable at initialization.
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.
Sets the token header key name.
get-token
Configuration for the token acquisition endpoint.
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.
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.