Conventions

Every extra attribute a client can send to the gateway travels through one of three channels, chosen by a single rule:

Body fields

Field	Purpose
`user`	OpenAI-standard end-user id — forwarded to the provider
`metadata`	Arbitrary tags — stripped before forwarding, stored on the log
`prompt_id`	Link the request to a saved prompt
`output_schema`	Structured output configuration
`fallback_chain`	Fallback models with trigger conditions

Body fields are typed JSON: no header size caps, no latin-1 encoding issues, and any OpenAI-compatible client can send them without custom plumbing.

Header	Purpose
`x-gatelit-end-user-id`	End-user id for log attribution — never forwarded
`x-gatelit-request-source`	`api` / `dashboard` / `eval`
`x-gatelit-parent-request-id`	Correlation for synthetic requests (prompt runs)
`x-gatelit-internal-secret`	Dashboard ↔ gateway internal calls
`x-gatelit-request-id`, `x-gatelit-model`, `x-gatelit-auth-mode`, …	Response metadata

Headers carry transport context set by auth layers and middleware. They never reach the provider — a security property, not just style.

sub, orgId, model, maxTokens, endUserId, requestSource — identity issued by the backend when minting a signed token.

When the same concept can arrive through multiple channels (end-user id):

token claim > header > body user

Would a client set it on every request without touching auth? → body
Is it set by infrastructure or auth, and must it never reach the provider? → header (or token claim)
Does it describe the authenticated identity? → token claim