feat: allow overriding headers per request

config/clients/go/CHANGELOG.md.mustache

@@ -2,6 +2,8 @@
 
 ## [Unreleased](https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}/compare/v{{packageVersion}}...HEAD)
 
+- feat: add support for custom headers per request. See [documentation](https://github.com/openfga/go-sdk#custom-headers).
+
 ## {{packageVersion}}
 
 ### [{{packageVersion}}](https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}/compare/v0.7.1...v{{packageVersion}}) (2025-09-15)

config/clients/go/config.overrides.json

@@ -45,6 +45,12 @@
       "destinationFilename": "client/errors.go",
       "templateType": "SupportingFiles"
     },
+    "client/client_headers_test.go": {
+      "destinationFilename": "client/client_headers_test.go"
+    },
+    "api_headers_test.go": {
+      "destinationFilename": "api_headers_test.go"
+    },
     "api_client_test.mustache": {
       "destinationFilename": "api_client_test.go",
       "templateType": "SupportingFiles"

config/clients/go/template/README_initializing.mustache

@@ -114,3 +114,43 @@ func main() {
     }
 }
 ```
+
+### Custom Headers
+
+#### Default Headers
+You can set default headers that will be sent with every request during client initialization:
+
+```golang
+fgaClient, err := client.NewSdkClient(&client.ClientConfiguration{
+    ApiUrl:               os.Getenv("FGA_API_URL"),
+    StoreId:              os.Getenv("FGA_STORE_ID"),
+    AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
+    DefaultHeaders: map[string]string{
+        "X-Custom-Header": "default-value",
+        "X-Request-Source": "my-app",
+    },
+})
+```
+
+#### Per-Request Headers
+
+You can also send custom headers on a per-request basis by using the `Options` parameter. Custom headers will override any default headers set in the client configuration.
+
+```golang
+// Add custom headers to a specific request
+checkResponse, err := fgaClient.Check(context.Background()).
+    Body(client.ClientCheckRequest{
+        User:     "user:anne",
+        Relation: "viewer",
+        Object:   "document:roadmap",
+    }).
+    Options(client.ClientCheckOptions{
+        RequestOptions: client.RequestOptions{
+            Headers: map[string]string{
+                "X-Request-ID": "123e4567-e89b-12d3-a456-426614174000",
+                "X-Custom-Header": "custom-value", // these override any default headers set
+            },
+        },
+    }).
+    Execute()
+```

config/clients/go/template/api.mustache

@@ -24,6 +24,10 @@ var (
 )
 {{#generateInterfaces}}
 
+type RequestOptions struct {
+	Headers     map[string]string `json:"headers,omitempty"`
+}
+
 type {{classname}} interface {
 	{{#operation}}
 
@@ -61,13 +65,20 @@ type {{#structPrefix}}{{&classname}}{{/structPrefix}}Api{{operationId}}Request s
 {{#allParams}}
     {{paramName}} {{^isPathParam}}*{{/isPathParam}}{{{dataType}}}
 {{/allParams}}
+  options    RequestOptions
 }
+
 {{#allParams}}{{^isPathParam}}
 func (r {{#structPrefix}}{{&classname}}{{/structPrefix}}Api{{operationId}}Request) {{vendorExtensions.x-export-param-name}}({{paramName}} {{{dataType}}}) {{#structPrefix}}{{&classname}}{{/structPrefix}}Api{{operationId}}Request {
 	r.{{paramName}} = &{{paramName}}
 	return r
 }{{/isPathParam}}{{/allParams}}
 
+func (r {{#structPrefix}}{{&classname}}{{/structPrefix}}Api{{operationId}}Request) Options(options RequestOptions) {{#structPrefix}}{{&classname}}{{/structPrefix}}Api{{operationId}}Request {
+	r.options = options
+	return r
+}
+
 func (r {{#structPrefix}}{{&classname}}{{/structPrefix}}Api{{operationId}}Request) Execute() ({{#returnType}}{{{.}}}, {{/returnType}}*http.Response, error) {
 	return r.ApiService.{{nickname}}Execute(r)
 }
@@ -281,6 +292,7 @@ func (a *{{{classname}}}Service) {{nickname}}Execute(r {{#structPrefix}}{{&class
 	// body params
 	requestBody = r.{{paramName}}
 {{/bodyParams}}
+
 {{#authMethods}}
 {{#isApiKey}}
 {{^isKeyInCookie}}
@@ -318,6 +330,11 @@ func (a *{{{classname}}}Service) {{nickname}}Execute(r {{#structPrefix}}{{&class
 {{/isApiKey}}
 {{/authMethods}}
 
+	// if any override headers were in the options, set them now
+	for header, val := range r.options.Headers {
+		localVarHeaderParams[header] = val
+  }
+
     retryParams := a.client.cfg.RetryParams
 	for i := 0; i < retryParams.MaxRetry+1; i++ {
 	req, err := a.client.prepareRequest(r.ctx, path, httpMethod, requestBody, localVarHeaderParams, localVarQueryParams)

config/clients/go/template/api_client.mustache

@@ -290,7 +290,9 @@ func (c *APIClient) prepareRequest(
 	localVarRequest.Header.Set("User-Agent", c.cfg.UserAgent)
 
 	for header, value := range c.cfg.DefaultHeaders {
-		localVarRequest.Header.Set(header, value)
+		if localVarRequest.Header.Get(header) == "" {
+			localVarRequest.Header.Set(header, value)
+		}
 	}
 
 	if ctx != nil {