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:

  1. No buffering of streaming responses: SSE must be forwarded chunk by chunk.
  2. WebSocket upgrade support: Responses WebSocket, Realtime, Live, and DeepSeek text-to-speech all depend on it.
  3. 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 handle OPTIONS preflight requests except for /x-pricing. Because the consoles run on separate domains, the proxy must answer preflights directly with 204 and 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, change Access-Control-Allow-Origin to the console domains.
  • client_max_body_size should be no smaller than REQUEST_BODY_LIMIT_BYTES (default 200 MiB).
  • If you split paths into multiple location blocks, every path that carries WebSocket (/v1/responses, /v1/realtime, /v1/live/, /v1/tools/tts) needs the Upgrade and Connection headers.
  • The Connection header uses a map: when Upgrade is present, the WebSocket upgrade is forwarded; otherwise an empty value is sent, keeping keep-alive connection reuse with the upstream.
  • underscores_in_headers on is required. By default Nginx drops request headers whose names contain underscores, so session_id and conversation_id would 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 reads CF-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)"