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

> Understand the x-sdk-name header in OpenHuman. Learn how it enables per-product analytics, quota enforcement, and billing attribution for Tiny Humans products.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: api-reference
- Published: 2026-08-28

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/api/product.rs) establishes the global identity, which subsequent clients automatically inherit.

```rust
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:

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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.