[Feature] Add support for per-request custom HTTP headers in SDK API calls

[dyeam0]

Checklist

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

Describe the problem you'd like to have solved

Problem statement

The Go SDK does not provide a direct way to add custom HTTP headers to the API requests they generate on a per-request basis. This limits the ability to pass along valuable contextual information from client applications to the OpenFGA server and any intermediate networking infrastructure (like API gateways or service meshes). For example, it's a common requirement to propagate tracing information (ex., correlation IDs, trace IDs, span IDs) or other internal metadata for logging, debugging, or routing purposes. Without this capability, we lose end-to-end observability and have a significant gap in viewing and using metadata appropriately.

Describe the ideal solution

Proposed solution

Enhance the Go SDK to allow developers to specify custom HTTP headers for each API call on a per-request basis. This could be achieved by adding an optional headers parameter to the method signature of the API client's functions (check, write, read, etc.).

This would give developers the flexibility to inject any necessary headers, such as:

• Internal request IDs for logging and correlation
• Distributed tracing headers
• Client-specific metadata for auditing purposes

Adding this capability would significantly improve the integration of OpenFGA into existing production systems in the areas of observability, auditing, debugging, and more.

Alternatives and current workarounds

They are less than ideal. One example:

• Correlation of a patchwork of internal application logs. This is a manual process or a brittle, custom internal integration.

References

No response

Additional context

No response