Checklist

• I agree to the terms within the OpenFGA Code of Conduct.

Describe the problem you'd like to have solved

Summary

The Python OpenFGA SDK supports sending custom HTTP headers with individual API requests using the [options["headers"] parameter, but this functionality currently lacks dedicated test coverage. We need tests to ensure this feature works reliably across all API methods and edge cases.

Background

The SDK allows users to send custom headers like this:

options = { "headers": { "x-correlation-id": "abc-123", "x-trace-id": "trace-456", "x-service-name": "my-service" } } response = await fga_client.check(body, options)

However, this feature is not explicitly tested, which creates several problems:

• No guarantee it works across all API methods
• Risk of regressions during SDK updates or refactoring
• No examples for developers on how to use this feature properly
• Uncertain compatibility between async and sync clients

Without proper test coverage, a user cannot rely on this functionality in production environments.

Describe the ideal solution

Success Criteria

• Tests verify headers work with all API methods that support options
• Edge cases and error scenarios are covered
• Both async and sync clients are tested
• Tests include practical examples that serve as documentation
• All tests pass consistently
• Feature behavior is clearly defined through test cases

Benefits

• Confidence - Users can trust the feature works reliably
• Regression Prevention - Catches breaking changes during development
• Production Readiness - Validates the feature handles real-world scenarios

Current Situation

Right now, if a user wants to use custom headers for tracing or service identification, they have to:

• Hope it works without any test validation
• Test it manually in their own code
• Risk discovering issues only in production
• Guess at the correct usage patterns

Alternatives and current workarounds

• Use options without being able to rely on whether the functionality is tested.
• Even if it were working at one point in time, without tests, it's not guaranteed that it will stay working.

References

• GitHub issue to add documentation: Add documentation and examples for per-request custom HTTP headers usage #215
• SDK generator GitHub issue to implement the feature in all SDKs: [Feature request] Add support for per-request custom HTTP headers in SDK API calls sdk-generator#569

Additional context

No response