feat: add headers configuration property (#232)

* docs: add custom headers guidance to README

* feat: add `headers` configuration property

---------

Co-authored-by: Ewan Harris <[email protected]>

Author: evansims

README.md

@@ -200,6 +200,66 @@ async def main():
         return api_response
 ```
 
+### Custom Headers
+
+#### Default Headers
+
+You can configure default headers that will be sent with every request by passing them to the `ClientConfiguration`:
+
+```python
+from openfga_sdk import ClientConfiguration, OpenFgaClient
+
+
+async def main():
+    configuration = ClientConfiguration(
+        api_url=FGA_API_URL,
+        store_id=FGA_STORE_ID,
+        authorization_model_id=FGA_MODEL_ID,
+        headers={
+            "X-Custom-Header": "default-value",
+            "X-Request-Source": "my-app",
+        },
+    )
+
+    async with OpenFgaClient(configuration) as fga_client:
+        api_response = await fga_client.read_authorization_models()
+        return api_response
+```
+
+#### Per-Request Headers
+
+You can also send custom headers on a per-request basis by using the `options` parameter. Per-request headers will override any default headers with the same name.
+
+```python
+from openfga_sdk import ClientConfiguration, OpenFgaClient
+from openfga_sdk.client.models import ClientCheckRequest
+
+
+async def main():
+    configuration = ClientConfiguration(
+        api_url=FGA_API_URL,
+        store_id=FGA_STORE_ID,
+        authorization_model_id=FGA_MODEL_ID,
+    )
+
+    async with OpenFgaClient(configuration) as fga_client:
+        # Add custom headers to a specific request
+        result = await fga_client.check(
+            body=ClientCheckRequest(
+                user="user:anne",
+                relation="viewer",
+                object="document:roadmap",
+            ),
+            options={
+                "headers": {
+                    "X-Request-ID": "123e4567-e89b-12d3-a456-426614174000",
+                    "X-Custom-Header": "custom-value",  # Overrides default header value
+                }
+            }
+        )
+        return result
+```
+
 #### Synchronous Client
 
 To run outside of an async context, the project exports a synchronous client

openfga_sdk/client/client.py

@@ -168,6 +168,11 @@ def __init__(self, configuration: ClientConfiguration):
         self._api_client = ApiClient(configuration)
         self._api = OpenFgaApi(self._api_client)
 
+        # Set default headers from configuration
+        if configuration.headers:
+            for header_name, header_value in configuration.headers.items():
+                self._api_client.set_default_header(header_name, header_value)
+
     async def __aenter__(self):
         return self
 

openfga_sdk/client/configuration.py

@@ -53,6 +53,7 @@ def __init__(
             ]
             | None
         ) = None,
+        headers: dict[str, str] | None = None,
     ):
         super().__init__(
             api_scheme,
@@ -64,6 +65,7 @@ def __init__(
             api_url=api_url,
             timeout_millisec=timeout_millisec,
             telemetry=telemetry,
+            headers=headers,
         )
         self._authorization_model_id = authorization_model_id
 

openfga_sdk/configuration.py

@@ -202,6 +202,7 @@ def __init__(
             | None
         ) = None,
         timeout_millisec: int | None = None,
+        headers: dict[str, str] | None = None,
     ):
         """Constructor"""
         self._url = api_url
@@ -326,6 +327,10 @@ def __init__(
         """Telemetry configuration
         """
 
+        self._headers = headers or {}
+        """Default headers to be sent with every request
+        """
+
     def __deepcopy__(self, memo):
         cls = self.__class__
         result = cls.__new__(cls)
@@ -656,6 +661,17 @@ def is_valid(self):
                     f"timeout_millisec not within reasonable range (0,60000), {self._timeout_millisec}"
                 )
 
+        if self._headers is not None:
+            for key, value in self._headers.items():
+                if not isinstance(key, str):
+                    raise FgaValidationException(
+                        f"header keys must be strings, got {type(key).__name__} for key {key}"
+                    )
+                if not isinstance(value, str):
+                    raise FgaValidationException(
+                        f"header values must be strings, got {type(value).__name__} for key '{key}'"
+                    )
+
     @property
     def api_scheme(self):
         """Return connection is https or http."""
@@ -740,3 +756,31 @@ def timeout_millisec(self, value):
         Update timeout milliseconds
         """
         self._timeout_millisec = value
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """
+        Return default headers to be sent with every request.
+
+        Headers are key-value pairs that will be included in all API requests.
+        Common use cases include correlation IDs, API versioning, and tenant identification.
+        """
+        return self._headers
+
+    @headers.setter
+    def headers(self, value: dict[str, str] | None) -> None:
+        """
+        Update default headers to be sent with every request.
+
+        Args:
+            value: Dictionary of header names to values, or None to clear headers.
+                   Both keys and values must be strings.
+
+        Raises:
+            FgaValidationException: If value is not a dict or None.
+        """
+        if value is not None and not isinstance(value, dict):
+            raise FgaValidationException(
+                f"headers must be a dict or None, got {type(value).__name__}"
+            )
+        self._headers = value or {}

openfga_sdk/sync/client/client.py

@@ -169,6 +169,11 @@ def __init__(self, configuration: ClientConfiguration) -> None:
         self._api_client = ApiClient(configuration)
         self._api = OpenFgaApi(self._api_client)
 
+        # Set default headers from configuration
+        if configuration.headers:
+            for header_name, header_value in configuration.headers.items():
+                self._api_client.set_default_header(header_name, header_value)
+
     def __enter__(self):
         return self