HTTP Headers
OpenGateway request headers for API authentication, request correlation, end-user attribution, session attribution, and dashboard log filtering.
OpenGateway accepts standard HTTP headers such as Authorization and
Content-Type. The public gateway-specific headers currently record request
attribution and correlation metadata for logs.
What you get#
- User and session attribution — group requests in logs and dashboards
- Task ID — correlate one logical job across many requests
Every header is optional. A bare OpenAI request works without any of them.
Reference#
| Header | Purpose | Example |
|---|---|---|
Authorization | API key. Required. | Bearer og_live_... |
Content-Type | Always application/json for chat completions. | application/json |
x-opengateway-user-id | End-user identifier for analytics. Free-form string. | user_42 |
x-opengateway-session-id | Session identifier for analytics. | sess_abc |
x-sionic-task-id | Logical task ID. Surfaces in dashboards as a request group. | task_2026_05_01_billing_run |
User and session attribution#
Pass x-opengateway-user-id and x-opengateway-session-id to break down
usage in the dashboard. Both are free-form strings the gateway never
interprets — they show up alongside the request in logs.
-H "x-opengateway-user-id: user_42" \
-H "x-opengateway-session-id: sess_a1b2c3"Use case: you run a B2B SaaS and want per-customer cost attribution. Set
user-id to the customer ID and session-id to the conversation ID.
Filter the dashboard by either, and the answer is one query away.
Task ID#
x-sionic-task-id is a logical task identifier that survives across many
requests. Use it when one user-visible action triggers several gateway calls
(planner → executor → critic, RAG → answer, etc.). All requests with the
same task ID surface as a single group.
-H "x-sionic-task-id: task_invoice_classify_2026_05_01"What to know#
Are these headers stable?#
They are the currently implemented public gateway headers.
Do standard OpenAI headers work?#
The gateway only interprets the headers listed above. Provider-specific OpenAI headers are not part of the documented public surface.
How do I configure fallbacks?#
Use request body fields. Chat fallbacks live under extra.fallbacks.