What Is the `x-sdk-name` Header in OpenHuman? Purpose and Implementation

The x-sdk-name header is a custom HTTP header that identifies which Tiny Humans product (OpenHuman, OpenCompany, or Medulla) is making a request to the shared backend, enabling per-product analytics, quota enforcement, and billing attribution.

OpenHuman (openhuman_core) communicates with the Tiny Humans backend for authentication, data storage, and service orchestration. Since the same backend infrastructure serves multiple products, the x-sdk-name header provides the canonical mechanism for distinguishing the origin of each request.

Why OpenHuman Uses the x-sdk-name Header

Product Attribution Across Multiple Services

The Tiny Humans ecosystem includes several distinct products—OpenHuman, OpenCompany, and Medulla—that all share the same backend infrastructure. Without explicit identification, the server would merge all traffic into a single undifferentiated stream, making it impossible to track usage per product or enforce separate rate limits.

The backend reads the x-sdk-name header (processed in tinyhumansai/backend/src/utils/sdkSource.ts) to attribute each call to its originating product. This separation powers distinct analytics dashboards, quota enforcement policies, and billing calculations for each product line.

Process-Wide Identity Management

OpenHuman stores the header value globally at the process level in src/api/product.rs. The system sets this identity once during startup via set_product_identity, before any backend client is instantiated.

Once initialized, all SDK-based transports—including BackendOAuthClient and IntegrationClient—automatically pull the current identity and inject it into their default headers. This ensures consistency across the entire application lifecycle without requiring manual header configuration for every request.

How the x-sdk-name Header Is Implemented

Header Sanitization and Safety

To guarantee that the identity value can always be converted into a valid HeaderValue, OpenHuman sanitizes the input string through ProductIdentity::new in src/api/product.rs. The validation enforces strict constraints:

• Permits only ASCII alphanumerics, periods (.), underscores (_), and hyphens (-)
• Converts all characters to lowercase
• Enforces a maximum length of 64 bytes

The default identity is "openhuman", though embedding products can override this value (for example, "opencompany"). This immutability after startup prevents accidental identity switching during runtime.

Selective Propagation to Third Parties

Not every outbound request carries the x-sdk-name header. The download_client used by IntegrationClient (defined in src/openhuman/integrations/client.rs) intentionally excludes the header because requests may follow redirects to third-party storage endpoints. Including the header in these scenarios would leak the product name to external services.

All other backend-bound transports retain the header, ensuring the backend receives proper attribution while protecting sensitive product identity information from external leakage.

Setting and Overriding the Product Identity

Embedding products can override the default "openhuman" identity before initializing any backend clients. The set_product_identity function in src/api/product.rs establishes the global identity, which subsequent clients automatically inherit.

use openhuman_core::api::{set_product_identity, ProductIdentity};

fn main() {
    // Override the default product name for an embedding product (e.g., OpenCompany)
    if let Some(id) = ProductIdentity::new("opencompany") {
        set_product_identity(id);
    }

    // After this point any BackendOAuthClient or IntegrationClient created
    // will automatically add `x-sdk-name: opencompany` to every request header.
    let client = openhuman_core::api::rest::BackendOAuthClient::new(
        "https://api.tinyhumans.ai".into(),
        "my-jwt".into(),
    );
}

For rare cases requiring manual header construction, the product_identity_headers function returns a HeaderMap containing the pre-configured x-sdk-name value:

use openhuman_core::api::product::product_identity_headers;
use reqwest::header::HeaderMap;

let mut headers: HeaderMap = product_identity_headers(); // contains x-sdk-name
// Use `headers` with any custom reqwest client

Summary

• Product differentiation: The x-sdk-name header enables the Tiny Humans backend to distinguish between OpenHuman, OpenCompany, and Medulla traffic for analytics and billing.
• Global configuration: Set once via set_product_identity in src/api/product.rs, the value persists for all backend clients created afterward.
• Safety constraints: The ProductIdentity::new constructor sanitizes input to ensure valid ASCII, lowercase formatting, and 64-byte limits.
• Selective omission: The download_client excludes the header to prevent leaking product names to third-party storage during redirects.
• Default behavior: Unmodified OpenHuman instances automatically send x-sdk-name: openhuman unless explicitly overridden.

Frequently Asked Questions

What is the default value of the x-sdk-name header in OpenHuman?

The default value is "openhuman". This string is defined as the fallback identity in src/api/product.rs and is applied automatically if no embedding product calls set_product_identity during initialization.

Can embedding products customize the x-sdk-name header?

Yes. Embedding products like OpenCompany can override the default by calling ProductIdentity::new("opencompany") followed by set_product_identity before instantiating any backend clients. Once set, all subsequent requests from BackendOAuthClient and IntegrationClient will carry the custom value.

Why doesn't the download client include the x-sdk-name header?

The download_client used by IntegrationClient excludes the header to prevent information leakage. Since download requests may redirect to third-party storage services (S3, Azure Blob, etc.), including the header would expose the product name to external infrastructure outside the Tiny Humans ecosystem.

How does the backend use the x-sdk-name header?

The backend middleware (located in tinyhumansai/backend/src/utils/sdkSource.ts) extracts the header value to attribute incoming requests to specific products. This attribution drives per-product rate limiting, usage analytics, and billing calculations, ensuring each product's traffic is tracked independently even though they share the same API infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}