Reverse Proxy
XSI itself serves plain HTTP; HTTPS is handled by a reverse proxy in front of it. The API entry point places three requirements on the proxy:
- No buffering of streaming responses: SSE must be forwarded chunk by chunk.
- WebSocket upgrade support: Responses WebSocket, Realtime, Live, and DeepSeek text-to-speech all depend on it.
- Long enough timeouts: long reasoning and long-lived connections can last tens of minutes.
The proxy must also pass the real client IP to XSI, which uses it for IP allowlists, authentication failure bans, and signup abuse prevention.
Real client IP
XSI reads forwarding headers only when the connection comes from TRUSTED_PROXY_CIDRS (loopback and RFC 1918 private ranges by default): it first takes the first untrusted address from the right of X-Forwarded-For, then checks CF-Connecting-IP, True-Client-IP, and X-Real-IP in that order. Connections from any other address use the peer IP directly.
- If the proxy runs on the same host as XSI or in the same private network, keep the default.
- If the proxy sits at another public address, add its address to
TRUSTED_PROXY_CIDRS. - Do not add arbitrary public ranges to the trusted list, or clients will be able to spoof their IP.
Before forwarding to the upstream, XSI removes every header related to the client IP, so the upstream never sees end users' addresses.
Nginx
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}
upstream xsi_api {
server 127.0.0.1:5443;
keepalive 256;
}
server {
listen 443 ssl;
http2 on;
server_name api.example.com;
ssl_certificate /etc/nginx/certs/api.example.com.crt;
ssl_certificate_key /etc/nginx/certs/api.example.com.key;
client_max_body_size 200m;
underscores_in_headers on; # keep sticky-session headers such as session_id and conversation_id
location / {
# CORS: required when the consoles and browser apps call the API cross-origin
if ($request_method = 'OPTIONS') {
add_header Access-Control-Allow-Origin '*';
add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Api-Key, X-Goog-Api-Key, Anthropic-Version, Anthropic-Beta, OpenAI-Beta, OpenAI-Organization, OpenAI-Project, Session_Id, Conversation_Id, Idempotency-Key';
add_header Access-Control-Max-Age 1728000;
add_header Content-Length 0;
return 204;
}
add_header Access-Control-Allow-Origin '*' always;
add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS' always;
add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Api-Key, X-Goog-Api-Key, Anthropic-Version, Anthropic-Beta, OpenAI-Beta, OpenAI-Organization, OpenAI-Project, Session_Id, Conversation_Id, Idempotency-Key' always;
proxy_pass http://xsi_api;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# Streaming responses
proxy_buffering off;
proxy_request_buffering off;
# Long reasoning and long-lived connections
proxy_connect_timeout 10s;
proxy_send_timeout 3600s;
proxy_read_timeout 3600s;
}
}
server {
listen 443 ssl;
http2 on;
server_name admin.example.com;
ssl_certificate /etc/nginx/certs/admin.example.com.crt;
ssl_certificate_key /etc/nginx/certs/admin.example.com.key;
location / {
proxy_pass http://127.0.0.1:5080;
proxy_set_header Host $host;
}
}
server {
listen 443 ssl;
http2 on;
server_name manage.example.com;
ssl_certificate /etc/nginx/certs/manage.example.com.crt;
ssl_certificate_key /etc/nginx/certs/manage.example.com.key;
location / {
proxy_pass http://127.0.0.1:5081;
proxy_set_header Host $host;
}
}Key points:
- CORS is provided by the proxy. XSI does not send
Access-Control-Allow-*response headers, nor does it handleOPTIONSpreflight requests except for/x-pricing. Because the consoles run on separate domains, the proxy must answer preflights directly with204and attach the CORS headers, or the consoles cannot sign in. XSI sets the exposure of pagination response headers (Access-Control-Expose-Headers) itself. To tighten access, changeAccess-Control-Allow-Originto the console domains. client_max_body_sizeshould be no smaller thanREQUEST_BODY_LIMIT_BYTES(default 200 MiB).- If you split paths into multiple
locationblocks, every path that carries WebSocket (/v1/responses,/v1/realtime,/v1/live/,/v1/tools/tts) needs theUpgradeandConnectionheaders. - The
Connectionheader uses a map: whenUpgradeis present, the WebSocket upgrade is forwarded; otherwise an empty value is sent, keeping keep-alive connection reuse with the upstream. underscores_in_headers onis required. By default Nginx drops request headers whose names contain underscores, sosession_idandconversation_idwould be lost, lowering sticky-session and prompt cache hit rates.
Caddy
api.example.com {
reverse_proxy 127.0.0.1:5443 {
flush_interval -1
transport http {
read_timeout 3600s
write_timeout 3600s
}
}
}
admin.example.com {
reverse_proxy 127.0.0.1:5080
}
manage.example.com {
reverse_proxy 127.0.0.1:5081
}Caddy obtains certificates automatically, passes WebSocket through, and sets X-Forwarded-For by default. Add the CORS headers and OPTIONS preflight responses the consoles need for cross-origin access with the header and respond directives, following the Nginx example above.
CDN and Cloudflare
- When traffic passes through a CDN such as Cloudflare, make sure the CDN's origin-pull addresses or ranges are within
TRUSTED_PROXY_CIDRS(or let a same-host proxy handle them); XSI readsCF-Connecting-IP. - A CDN's response timeout can be shorter than long reasoning requires (for example, 100 seconds on Cloudflare's free plan); when exceeded, the client receives
524. For long requests, use streaming responses or let the API domain bypass the CDN proxy. - Do not cache API responses on the CDN.
Consoles
Both consoles are purely static sites. The Nginx inside the container already sets the caching policy (HTML and config.js are not cached; versioned JS/CSS is cached for one year), so the front proxy only needs to pass traffic through. The consoles call the API domain directly from the browser, so the API entry point must provide the CORS configuration above.
Verify
# Streaming: output should arrive chunk by chunk, not all at once at the end
curl -N "https://api.example.com/v1/chat/completions" \
-H "Authorization: Bearer $XSI_API_KEY" -H "Content-Type: application/json" \
-d '{"model":"gpt-6.2-sol","stream":true,"messages":[{"role":"user","content":"Count to 20"}]}'
# WebSocket: should return 101 Switching Protocols
curl -i -N "https://api.example.com/v1/responses" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Connection: Upgrade" -H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: $(openssl rand -base64 16)"