Skip to navigation
OpenAPI

Authentication

View as Markdown

Fern supports two ways to configure authentication:

  • In your OpenAPI spec using securitySchemes — the standard approach that keeps auth configuration portable and works with other OpenAPI tools.
  • In generators.yml using auth-schemes — use this to customize parameter names and environment variables, override what’s defined in your spec, or configure OAuth (which isn’t available in OpenAPI).

Your authentication configuration applies across generated SDKs and the API Explorer. All SDKs support both direct configuration and environment variables for credentials. If you define the same scheme in both places, generators.yml takes precedence.

Configure authentication in your spec

Define your schemes in components.securitySchemes, then apply them globally or per-endpoint using the security property.

openapi.yml
# Define the scheme
components:
  securitySchemes:
    BearerAuth: # User-defined scheme name
      type: http
      scheme: bearer
# Apply globally across all endpoints
security:
  - BearerAuth: []

Generated SDK usage:

index.ts
const client = new Client({
  token: "ey34..."
});
openapi.yml
components:
  securitySchemes:
    BearerAuth: # User-defined scheme name
      type: http
      scheme: bearer

To customize parameter names and environment variables, add x-fern-bearer:

openapi.yml
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      x-fern-bearer:
        name: apiKey
        env: PLANTSTORE_API_KEY
openapi.yml
components:
  securitySchemes:
    BasicAuth: # User-defined scheme name
      type: http
      scheme: basic

To customize parameter names and environment variables, add x-fern-basic:

openapi.yml
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      x-fern-basic:
        username:
          name: clientId
          env: PLANTSTORE_CLIENT_ID
        password:
          name: clientSecret
          env: PLANTSTORE_CLIENT_SECRET
openapi.yml
components:
  securitySchemes:
    ApiKeyAuth: # User-defined scheme name
      type: apiKey
      in: header
      name: X_API_KEY

To customize parameter names and environment variables, add x-fern-header:

openapi.yml
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X_API_KEY
      x-fern-header:
        name: apiToken
        env: PLANTSTORE_API_KEY
        prefix: "Token "

The prefix option automatically prepends a string to API keys, useful when your API expects formats like "Bearer abc123" or "Token abc123".

Playground-only descriptions

A security scheme’s description appears in the API Reference’s Authorization section. To show extra guidance only in the API Explorer, such as where to generate a token, add x-fern-playground-description. It renders as an info callout beneath the auth input and leaves the API Reference unchanged.

openapi.yml
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Use your account API token.
      x-fern-playground-description: |-
        Generate a short-lived token in the [dashboard](https://plantstore.example.com/tokens).

The extension works on bearer, basic, API key header, and OAuth schemes. The value supports Markdown links, bare URLs, inline code, and blank-line-separated paragraphs; other Markdown renders as plain text.

Multiple auth schemes

Configure endpoints to support multiple authentication schemes or combinations. In the security section, multiple top-level items are OR options, while schemes within a single item are combined with AND.

openapi.yml
components:
  securitySchemes:
    bearerAuth: # User-defined scheme name
      type: http
      scheme: bearer
    basicAuth: # User-defined scheme name
      type: http
      scheme: basic
    apiKey: # User-defined scheme name
      type: apiKey
      in: header
      name: X-API-Key
paths:
  /plant/search/status:
    get:
      summary: Search plants by status
      security:
        - bearerAuth: []           # Option 1: Bearer token only
        - basicAuth: []            # Option 2: Basic auth AND API key
          apiKey: []

In this example, users can authenticate with either a bearer token OR with both basic auth and an API key together.

When using OAuth client credentials with multiple schemes, ensure the scheme name in your OpenAPI spec’s security section matches the name defined in generators.yml.

Customize or override authentication in generators.yml

Define your scheme in auth-schemes, then apply it as the default across all endpoints with api.auth:

generators.yml
# Define the scheme
auth-schemes:
  BearerAuth: # User-defined scheme name
    scheme: bearer
    token:
      name: apiKey
      env: PLANTSTORE_API_KEY
# Apply it as the default across all endpoints
api:
  auth: BearerAuth
  specs:
    - openapi: ./openapi.yml

Instead of a default scheme, set api.auth: endpoint-security to have generated SDKs honor each endpoint’s own security requirements.

For complete configuration options, see the auth-schemes reference. You can also override authentication settings for a specific SDK.

Generated SDK usage:

index.ts
// Uses process.env.PLANTSTORE_API_KEY
const client = new PlantStoreClient();
// Or provide explicitly
const client = new PlantStoreClient({
  apiKey: "your-api-key"
});
generators.yml
auth-schemes:
  BearerAuth: # User-defined scheme name
    scheme: bearer
    token:
      name: apiKey
      env: MY_API_KEY
generators.yml
auth-schemes:
  BasicAuth: # User-defined scheme name
    scheme: basic
    username:
      name: clientId
      env: MY_CLIENT_ID
    password:
      name: clientSecret
      env: MY_CLIENT_SECRET

Set omit: true on username or password to remove it from the generated SDK.

generators.yml
auth-schemes:
  ApiKeyAuth: # User-defined scheme name
    header: X-API-Key
    name: apiKey
    env: MY_API_KEY
    prefix: "Token "
generators.yml
auth-schemes:
  OAuth: # User-defined scheme name
    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: $request.client_id
        client-secret: $request.client_secret
      response-properties:
        access-token: $response.access_token
        expires-in: $response.expires_in
        refresh-token: $response.refresh_token
    refresh-token:
      endpoint: "POST /oauth/refresh"
      request-properties:
        refresh-token: $request.refresh_token
      response-properties:
        access-token: $response.access_token
        expires-in: $response.expires_in

The endpoint values reference paths in your OpenAPI spec. request-properties values must use the $request.<property> form and response-properties values the $response.<property> form; fern check rejects unprefixed names. When expires-in is returned, the SDK automatically refreshes tokens before they expire.

If your API uses namespaces (multiple API specs), prefix the endpoint with the namespace and ::. For example, "payments::POST /oauth/token".

To enable OAuth client credentials in the API Explorer, set playground.oauth on your API Reference entry in docs.yml. With it enabled, an x-fern-playground-description on the OAuth security scheme appears beneath the client credentials input.

docs.yml
navigation:
  - api: API Reference
    playground:
      oauth: true