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

# Conventions

> How attributes travel between clients, the gateway, and providers — and why each channel exists.

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

* **Body** — *request semantics*: what the client asks the gateway to do
* **Headers** — *transport context*: who the request is from and how it arrived
* **Token claims** — *identity*: scoped to the auth session

## 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.

## Headers

| 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.

## Token claims

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

## Precedence

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

```
token claim > header > body user
```

## Picking a channel for a new attribute

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