Configure Global Headers

How it works for SDK users

Once you configure a global header (either automatically detected or manually specified), Fern generates an SDK that accepts this as a constructor parameter. Users can then provide the value once, and the generated SDK automatically includes the header in all their API calls:

1 import os
2 
3 class Client:
4 
5   def __init__(self, *, apiKey: str):

Specifying global headers

Fern automatically identifies headers that are used in every request, or the majority of requests, and marks them as global. You can manually configure additional global headers in either api.yml (Fern Definition) or openapi.yml.

Fern Definition

To specify headers that are meant to be included on every request:

api.yml

1 name: api
2 headers:
3   X-App-Id: string

Global path parameters

You can also specify path parameters that are meant to be included on every request:

api.yml

1 name: api
2 base-path: /{userId}/{orgId}
3 path-parameters:
4   userId: string
5   orgId: string

Overriding the base path

If you have certain endpoints that do not live at the configured base-path, you can override the base-path at the endpoint level.

imdb.yml

1 service: 
2   endpoints: 
3     getMovie: 
4       method: POST
5       base-path: "override/{arg}"
6       path: "movies/{movieId}"
7       path-parameters: 
8         arg: string

You cannot yet specify query parameters that are meant to be included on every request. If you’d like to see this feature, please upvote this issue.

OpenAPI

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

openapi.yml

1 x-fern-global-headers:
2   - header: custom_api_key
3     name: api_key
4   - header: userpool_id
5     optional: true

This configuration yields the following client:

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

1	import os
2
3	class Client:
4
5	def __init__(self, *, apiKey: str):

1	name: api
2	base-path: /{userId}/{orgId}
3	path-parameters:
4	userId: string
5	orgId: string

1	service:
2	endpoints:
3	getMovie:
4	method: POST
5	base-path: "override/{arg}"
6	path: "movies/{movieId}"
7	path-parameters:
8	arg: string

1	x-fern-global-headers:
2	- header: custom_api_key
3	name: api_key
4	- header: userpool_id
5	optional: true

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