Global headers

At times, your API will leverage certain headers for every endpoint, or the majority of them, we call these “global headers”. For convenience, generated Fern SDKs expose “global headers” to easily be updated on API calls. Take for example an API key, if we declare the API key as a global header, a user will be able to plug theirs in easily:

import os
class Client:
  def __init__(self, *, apiKey: str):

Fern automatically pulls out headers that are used in every request, or the majority of requests, and marks them as global.

In your OpenAPI spec

To label additional headers as global, or to alias the names of global headers, use the x-fern-global-headers extension:

x-fern-global-headers:
  - header: custom_api_key
    name: api_key
  - header: userpool_id
    optional: true

Default values

Set a client-side default value on a global header using x-fern-default. The generated SDK makes the header optional and sends the default when the caller omits it:

x-fern-global-headers:
  - header: X-API-Version
    name: version
    x-fern-default: "2024-02-08"

In generators.yml

Alternatively, you can add headers to the api block in your generators.yml file:

api:
  specs:
    - openapi: ./path/to/openapi
  headers:
    custom_api_key:
      name: api_key
      type: string
    userpool_id:
      name: userpool_id
      type: optional<string>

Generated SDK behavior

Both configurations yield the following client code:

import os
class Client:
  def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str])