> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attribute LiteLLM spend per user

> Connect a LiteLLM proxy as a BYOK model and send a per-user identifier so the gateway can attribute spend.

Send a per-user identifier with completion requests so LiteLLM can attribute spend and apply customer budgets. This is attribution only. Langdock does not authenticate to LiteLLM with each user's token, and it does not show LiteLLM spend back in Langdock.

The setup is the same on Cloud and Dedicated until you create the model key. Dedicated keys also show **Authentication method**. Keep **API Key** for spend attribution.

> [!NOTE]
>
> **User identifier** appears on completion models only, in the catalog and in manual setup. Image and embedding wizards do not include it.

## Prerequisites

* Admin access to your Langdock workspace
* A LiteLLM proxy reachable over HTTPS
* The model alias from your LiteLLM config
* An API key if your proxy requires authentication

> [!WARNING]
>
> Langdock blocks requests to private IPs, localhost, and internal hostnames. Contact [support@langdock.com](mailto:support@langdock.com) if you need to reach an internal LiteLLM endpoint.

## Connect LiteLLM

### 1. Open the model wizard

Go to [Workspace Settings -> Models](https://app.langdock.com/settings/workspace/models) and click **Add custom model**.

![Models page with All, Completion, Image, and Custom filters, search, and Add custom model](https://mintcdn.com/langdock-34/8p_iScUTTv6VhSUA/images/litellm_add_model.png?fit=max\&auto=format\&n=8p_iScUTTv6VhSUA\&q=85\&s=d96d2f2aab032583095abf194a09fe2c)

### 2. Start from the catalog or set up manually

Pick a completion model from the catalog if LiteLLM serves a model Langdock already ships. Otherwise click **set up manually**.

![Add model wizard on Select Models, with catalog cards and set up manually in the footer](https://mintcdn.com/langdock-34/8p_iScUTTv6VhSUA/images/litellm_catalog.png?fit=max\&auto=format\&n=8p_iScUTTv6VhSUA\&q=85\&s=e4a2d6b41b6eeffed19adfa495c523a0)

For a manual model, fill **Model Name** and **Provider Model Name**. Those names are what Langdock shows in the picker. The LiteLLM alias belongs on the deployment in the next steps.

### 3. Set User identifier

On **Configure**, open **Advanced** and set **User identifier**. Choose **Microsoft UPN** when LiteLLM customers are keyed by Microsoft login.

![User identifier set to Microsoft UPN, with the dropdown open on None, User ID, E-Mail, and Alternative email](https://mintcdn.com/langdock-34/8p_iScUTTv6VhSUA/images/litellm_user_identifier.png?fit=max\&auto=format\&n=8p_iScUTTv6VhSUA\&q=85\&s=e18aad64e19ea939ecbe98ea73cff449)

Click **Continue**.

### 4. Add the LiteLLM key

On **Deployment**, click **New Key**. Set **Provider SDK** to **OpenAI Compatible**, **Base URL** to your proxy (for example `https://litellm.example.com/v1`), **API Key** to the proxy key, and **Hosting Provider** to a name your team will recognize.

> [tab] Cloud
>
> Cloud keys do not show **Authentication method**. The proxy key is enough.
>
> ![Create new API key for OpenAI Compatible with Base URL https://litellm.example.com/v1, API Key, and Hosting Provider LiteLLM](https://mintcdn.com/langdock-34/8p_iScUTTv6VhSUA/images/litellm_key_cloud.png?fit=max\&auto=format\&n=8p_iScUTTv6VhSUA\&q=85\&s=7ec47cfe6f3263af5633286bf84b6389)

> [tab] Dedicated
>
> Dedicated keys include **Authentication method**. Keep **API Key**. **User OAuth token** passes a signed-in user's token and is a different setup. Use **Client credentials** only if your proxy authenticates that way.
>
> ![Dedicated Create new API key with Authentication method open. Options are API Key, User OAuth token, and Client credentials. API Key is selected.](https://mintcdn.com/langdock-34/8p_iScUTTv6VhSUA/images/litellm_key_dedicated.png?fit=max\&auto=format\&n=8p_iScUTTv6VhSUA\&q=85\&s=4ed3fd3a98889dfdcd03f7bea88b9351)

Set **Model Name / ID** to the LiteLLM alias (the same value you put in LiteLLM `model_name`).

> [!NOTE]
>
> **Custom headers** on the model key are fixed text. They cannot include a per-user placeholder. Do not try to send `x-litellm-end-user-id` that way.

Click **Save key**, then **Test & continue**.

### 5. Save the model

On **Review**, confirm the deployment and that **User identifier** is set. Click **Save model**.

![Review step showing LiteLLM GPT-4o, the gpt-4o deployment on LiteLLM proxy, and User identifier set to userPrincipalName](https://mintcdn.com/langdock-34/8p_iScUTTv6VhSUA/images/litellm_review.png?fit=max\&auto=format\&n=8p_iScUTTv6VhSUA\&q=85\&s=f6c1ce4cbd6aa226d41e47813b1b7739)

For the rest of the OpenAI-compatible fields, see [Setup Guides](https://docs.langdock.com/en/admin/byok/setup-guides.md).

## Choose a User identifier

| Option | Value Langdock sends |
| - | - |
| **None** | No `x-user-id` header |
| **User ID** | The Langdock user ID |
| **E-Mail** | The user's email |
| **Alternative email** | The alternative email, or an empty `x-user-id` if that field is blank |
| **Microsoft UPN** | The UPN from Microsoft sign-in, or an empty `x-user-id` if none is stored |

**Microsoft UPN** is the right choice when LiteLLM customers are keyed by Microsoft login. Langdock stores that value from Microsoft sign-in. Other login methods may leave UPN empty.

## Map the identifier in LiteLLM

The header name is always `x-user-id`. You cannot change it.

If the model uses the **OpenAI** or **Azure** SDK, Langdock also sends a request-body `user` field when the identifier is non-empty. LiteLLM treats that body field as the customer ID with no extra config.

LiteLLM through **OpenAI Compatible** sends the header only. Map it in the LiteLLM `config.yaml`:

```yaml theme={null}
general_settings:
  user_header_mappings:
    - header_name: "x-user-id"
      litellm_user_role: "customer"
```

After this mapping, LiteLLM can track spend and apply customer budgets per identifier. See [LiteLLM customers](https://docs.litellm.ai/docs/proxy/customers).

If LiteLLM `validate_end_user_id_in_db` is on, the identifier is accepted only when it already matches a LiteLLM customer or an internal user's ID or email. Create those customer records in LiteLLM before you rely on that setting.

> [!WARNING]
>
> On **OpenAI Compatible**, Langdock sends the identifier only as `x-user-id`. Map that header in LiteLLM. The `user` field in the request body is not sent on this SDK.

## Limits

* Each completion model sends one identifier. You cannot send two fields at once.
* Empty `x-user-id` values (missing UPN or alternative email) still include the header. How LiteLLM treats an empty customer ID is up to your proxy.
* This does not replace per-user gateway tokens. Attribution and token-based auth are separate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.