Authentication

Configuring authentication schemes happens in the api.yml file.

$ 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

1 auth-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

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

Bearer authentication

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

api.yml

1 auth: Bearer                  
2 auth-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

1 const 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

1 auth: Bearer                  
2 auth-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
2 let client = new Client(); 
3 
4 // token has been renamed to apiKey
5 client = new Client({
6   apiKey: "ey34..."
7 })

Basic authentication

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

api.yml

1 auth: Basic                  
2 auth-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

1 const 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

1 auth: Basic                  
2 auth-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
2 let client = new Client(); 
3 
4 // parameters have been renamed
5 client = 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

1 auth: ApiKeyAuthScheme
2 auth-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

1 const 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

1 auth: ApiKeyAuthScheme
2 auth-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
2 let client = new Client(); 
3 
4 // parameters have been renamed
5 client = new Client({
6   apiKey: "ey34..."
7 })

OAuth client credentials

If your API uses OAuth, you can specify an oauth scheme. Note that you’ll need to define a token retrieval endpoint.

api.yml

1 name: api
2 
3 imports:
4   auth: auth.yml
5 
6 auth: OAuthScheme
7 auth-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.getToken               
15       response-properties:
16         access-token: $response.access_token 
17         expires-in: $response.expires_in

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.

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

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