Fern Definition

Authentication

Model auth schemes such as bearer, basic, custom headers, and oauth.

Configuring authentication schemes happens in the api.yml file. All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials.

$fern/
>├─ fern.config.json # root-level configuration
>├─ generators.yml # generators you're using
>└─ definition/
>  ├─ api.yml  # API-level configuration
>  └─ imdb.yml # endpoints, types, and errors

To add an authentication scheme, specify the authentication method under the auth-schemes section.

api.yml
1auth-schemes:
2  AuthScheme:                     
3    ...

To apply an authentication scheme across all endpoints, reference the auth-scheme within the auth section of your api.yml file.

api.yml
1auth: AuthScheme                  
2auth-schemes:
3  AuthScheme:                     
4    ...

Bearer authentication

Start by defining a Bearer authentication scheme in api.yml:

api.yml
1auth: Bearer                  
2auth-schemes:
3  Bearer:                     
4    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:

api.yml
1auth: Bearer                  
2auth-schemes:
3  Bearer:                     
4    scheme: bearer
5    token:
6      name: apiKey 
7      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 authentication

Start by defining a Basic authentication scheme in api.yml:

api.yml
1auth: Basic                  
2auth-schemes:
3  Basic:                     
4    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:

api.yml
1auth: Basic                  
2auth-schemes:
3  Basic:                     
4    scheme: basic
5    username:
6      name: clientId
7      env: PLANTSTORE_CLIENT_ID
8    password:
9      name: clientSecret
10      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})

Custom header (e.g. API key)

You can also create your own authentication scheme with customized headers.

api.yml
1auth: ApiKeyAuthScheme
2auth-schemes:
3  ApiKeyAuthScheme:
4    header: X-API-Key
5    type: string

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

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

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

api.yml
1auth: ApiKeyAuthScheme
2auth-schemes:
3  ApiKeyAuthScheme:
4    header: X-API-Key
5    type: string
6    name: apiKey
7    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// parameters have been renamed
5client = new Client({
6  apiKey: "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.

If your API uses OAuth, you can specify an oauth scheme in api.yml and define a token retrieval endpoint in a separate auth.yml file (example).

api.yml
1name: api
2
3imports:
4  auth: auth.yml
5
6auth: OAuthScheme
7auth-schemes:
8  OAuthScheme:
9    scheme: oauth
10    type: client-credentials
11    client-id-env: YOUR_CLIENT_ID
12    client-secret-env: YOUR_CLIENT_SECRET
13    get-token:
14      endpoint: auth.getTokenWithClientCredentials
15      request-properties:
16        client-id: $request.client_id         # Format: parameter-name: $request.property_name
17        client-secret: $request.client_secret # Format: parameter-name: $request.property_name            
18      response-properties:
19        access-token: $response.access_token  # Format: parameter-name: $response.property_name
20        expires-in: $response.expires_in      # Format: parameter-name: $response.property_name

The request-properties and response-properties map OAuth standard parameters to your actual endpoint’s request and response field names defined in auth.yml.

If the expires-in property is set, the generated OAuth token provider will automatically refresh the token when it expires. Otherwise, it’s assumed that the access token is valid indefinitely.

The corresponding auth.yml file (example) defines the token endpoint:

auth.yml
1types:
2  TokenResponse:
3    docs: |
4      An OAuth token response.
5    properties:
6      access_token: string
7      expires_in: integer
8      refresh_token: optional<string>
9
10service:
11  auth: false
12  base-path: /
13  endpoints:
14    getTokenWithClientCredentials:
15      path: /token
16      method: POST
17      request:
18        name: GetTokenRequest
19        body:
20          properties:
21            client_id: string
22            client_secret: string
23            audience: literal<"https://api.example.com">
24            grant_type: literal<"client_credentials">
25            scope: optional<string>
26      response: TokenResponse
If your OAuth server is hosted at a different URL than your main API, you can use multi-URL environments to specify separate base URLs for authentication and API calls.

With this, all of the OAuth logic happens automatically in the generated SDKs. As long as you configure these settings, your client will automatically retrieve an access token and refresh it as needed.

When using the docs playground, token-header and token-prefix can optionally be set to customize the header key name and header value prefix, to match the expected format of the API auth scheme.

For example, the following would produce a header Fern-Authorization: Fern-Bearer <token>:

api.yml
1auth-schemes:
2  OAuthScheme:
3    scheme: oauth
4    type: client-credentials
5    token-header: Fern-Authorization
6    token-prefix: Fern-Bearer
7    get-token:
8      ...