Skip to main content
A chat front-end authenticates to TrustGate with one API key and serves many people. Without help, every request from it carries the same consumer and the same principal, so Activity, Analytics and your cost reports can only say “this application” — never “this person”. End-user attribution closes that gap. A client tells TrustGate who it was serving, and that person lands on the trace, in Activity, and in the event stream alongside the credential that actually authenticated.
Attribution, not authentication. These values are asserted by whoever holds the API key and are never verified by the gateway. They never become the request’s principal, never reach policy decisions, and never grant access. They are for telemetry, analytics and cost attribution only. The authenticated principal is recorded separately and stays unchanged — see Not an identity.

​
Nothing to configure on TrustGate

There is no per-tenant setup, no flag on the consumer and no gateway setting. TrustGate reads the headers below on every request; a request that declares nobody behaves exactly as it did before.

​
Ways to declare the end user

TrustGate takes the first source that names somebody: TrustGate’s own namespace comes first on purpose: if you set X-TG-*, you did so deliberately, so a request carrying both yours and a vendor’s is attributed the way you asked. The body user field is a last resort — it is one opaque id, not a person — and is read only when no header named anyone. You do not have to send all four fields. Any one of id, email or name is enough; a header set where every value is blank is skipped, and the next source is tried.

​
Open WebUI

Open WebUI forwards its user headers when you turn on one environment variable. Set it where Open WebUI runs, not on TrustGate:
It is off by default. With it on, Open WebUI adds X-OpenWebUI-User-Id, -Email, -Name, -Role and X-OpenWebUI-Chat-Id to every request it sends to TrustGate, and attribution starts working with no further configuration on either side. If a proxy of your own sits between Open WebUI and TrustGate, check that it does not strip unknown request headers.

​
Your own client

Any client — a backend, a custom UI, a proxy — can attribute with TrustGate’s namespace:

​
The OpenAI user field

A client that already sets the OpenAI API’s user field needs no headers at all:
This is read only when no header declared anyone, and it can only carry an id — no email, name or role.

​
Grouping a conversation

A chat client sends each message as its own request. Without a conversation id every message looks like a fresh session, which makes session-scoped alerts and any “conversation” view useless. TrustGate takes the first of:
  1. The session header configured on the gateway (X-Session-Id by default)
  2. X-TG-Session-Id
  3. X-OpenWebUI-Chat-Id
  4. The body field named by the gateway’s session configuration, if set
  5. A generated id — one per request, which is the old behaviour
The value is recorded as session_id and echoed back on the response as X-Session-Id. Sessions are enabled by default; if a gateway sets session.enabled: false, none of these headers are read.

​
Where it shows up

Activity. The User column shows the declared person instead of the API key’s principal. Because the name is unverified it is marked as such, and opening a request shows who declared it and, beside it, the credential that authenticated — both facts at once. Event stream. Two fields on the TrustGate event, both documented in the Event schema: OpenTelemetry. Exported as trustgate.end_user plus trustgate.end_user.id, .email, .name, .role and .source. Values are trimmed and capped at 256 characters. A declaration that names nobody — only a role, say — records no identifier, so nothing groups under an empty user.

​
Not an identity

TrustGate distinguishes two different things, and so should any query you write over this data: Anyone who can reach your gateway with a valid API key can put any name in these headers. Use them to understand and bill traffic; do not use them to decide who may do what. If you need an end user whose identity TrustGate acts on, that is a different mechanism — see End users of your application for the MCP case, where each person connects their own upstream accounts.
  • Metrics worker: how the per-request event is built and exported
  • Event schema: the field contract alerts and analytics match on
  • Consumers: API keys, bindings, and the principal behind a request