Use Single x-okapi-tenant Header

Modules that erroneously send multiple x-okapi-tenant headers in API requests can cause unpredictable behavior, especially during cross-tenant requests. This intermittent issue can be difficult to diagnose.

Symptom

Cross-tenant HTTP requests may fail with 401 Unauthorized errors. The same request might succeed on the Okapi platform or fail unpredictably on Eureka.

Cause

Although HTTP allows multiple headers with the same name, FOLIO expects only one x-okapi-tenant header. When multiple headers are present, the system's behavior (which header value is used) is unpredictable. This usually occurs when a module attempts to override the x-okapi-tenant header injected by a shared library. Inconsistent capitalization (e.g., x-okapi-tenant vs. X-Okapi-Tenant) can result in multiple headers, rather than the intended replacement. Because HTTP header names are case-insensitive, these variations are treated as the same header, leading to a mismatch between the requested tenant and the authentication token. This mismatch causes authorization failures.

Recommendations

Ideally, modules should rely on shared libraries to manage all request headers. If modification is necessary, ensure that overriding header names exactly match those used by the shared library.

• Spring-based modules: Use the header names defined in org.folio.spring.integration.XOkapiHeaders.

• RMB-based modules: Use the header names defined in org.folio.okapi.common.XOkapiHeaders.

Note that these classes use different capitalizations and are not interchangeable.