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
1# Define the scheme
2components:
3  securitySchemes:
4    BearerAuth: # User-defined scheme name
5      type: http
6      scheme: bearer
7
8# Apply globally across all endpoints
9security:
10  - BearerAuth: []

Generated SDK usage:

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

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

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
openapi.yml
1components:
2  securitySchemes:
3    BasicAuth: # User-defined scheme name
4      type: http
5      scheme: basic

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

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
openapi.yml
1components:
2  securitySchemes:
3    ApiKeyAuth: # User-defined scheme name
4      type: apiKey
5      in: header
6      name: X_API_KEY

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

openapi.yml
1components:
2  securitySchemes:
3    ApiKeyAuth:
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 "

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

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
1components:
2  securitySchemes:
3    bearerAuth: # User-defined scheme name
4      type: http
5      scheme: bearer
6    basicAuth: # User-defined scheme name
7      type: http
8      scheme: basic
9    apiKey: # User-defined scheme name
10      type: apiKey
11      in: header
12      name: X-API-Key
13
14paths:
15  /plant/search/status:
16    get:
17      summary: Search plants by status
18      security:
19        - bearerAuth: []           # Option 1: Bearer token only
20        - basicAuth: []            # Option 2: Basic auth AND API key
21          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
1# Define the scheme
2auth-schemes:
3  BearerAuth: # User-defined scheme name
4    scheme: bearer
5    token:
6      name: apiKey
7      env: PLANTSTORE_API_KEY
8
9# Apply it as the default across all endpoints
10api:
11  auth: BearerAuth
12  specs:
13    - openapi: ./openapi.yml

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

Generated SDK usage:

index.ts
1// Uses process.env.PLANTSTORE_API_KEY
2const client = new PlantStoreClient();
3
4// Or provide explicitly
5const client = new PlantStoreClient({
6  apiKey: "your-api-key"
7});
generators.yml
1auth-schemes:
2  BearerAuth: # User-defined scheme name
3    scheme: bearer
4    token:
5      name: apiKey
6      env: MY_API_KEY
generators.yml
1auth-schemes:
2  BasicAuth: # User-defined scheme name
3    scheme: basic
4    username:
5      name: clientId
6      env: MY_CLIENT_ID
7    password:
8      name: clientSecret
9      env: MY_CLIENT_SECRET
generators.yml
1auth-schemes:
2  ApiKeyAuth: # User-defined scheme name
3    header: X-API-Key
4    name: apiKey
5    env: MY_API_KEY
6    prefix: "Token "
Pro and Enterprise feature

This feature is available on Pro and Enterprise plans. Contact support@buildwithfern.com to get started.

generators.yml
1auth-schemes:
2  OAuth: # User-defined scheme name
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

The endpoint values reference paths in your OpenAPI spec. When expires-in is returned, the SDK automatically refreshes tokens before they expire.