Skip to main content
createSessionProxyHandler is JavaScript. On any other backend, write the same relay in your own framework and render <OpenGeniChat baseUrl="/api/opengeni" /> (or the full SessionApp) against it. The relay forwards the signed-in user’s requests to the Opengeni API as that user. Opengeni’s permissions decide what each request may do; your relay only pins the workspace, adds the organization key and the user’s identity, and keeps closed whatever your product does not offer.

What to forward

Forward /api/opengeni/v1/<path> to /v1/<path> upstream, with the query string and body unchanged. Narrow the surface with the organization key’s permissions and each member’s permissions first: a request made as a user holds only the permissions both hold. Refuse any further routes your product keeps closed with a 404. If your server owns chat setup (it builds the agent, tools and MCP servers for each chat), also:
  • accept only initialMessage, idempotencyKey, file resources, and (unless you fix the model) model, reasoningEffort, latencyMode on POST workspaces/{ws}/sessions, and build the rest of the request on the server with your privacy settings;
  • refuse PUT sessions/{sid}/{agent|tool-policy|skills|variable-sets|usage-limit|visibility}, POST sessions/{sid}/{active-sandbox|codex-account|forks}, and POST workspaces/{ws}/chat/completions.
  • refuse browser GET sessions/{sid}/{configuration|model-context} too. Set Accept: application/json; opengeni-session=chat on upstream requests yourself, regardless of browser headers. Session responses then omit operator instructions, skill bodies and the full tool catalog. Requests without this Accept preference retain their historical full payload for old clients. Authorized backend readers use GET sessions/{sid}/configuration with sessions:control.
Private chats’ uploads. On POST workspaces/{ws}/files/uploads, when your chats are private (the default), add "scope": "personal" to a body that has no scope, so the file stays with the user who uploaded it, as in the Opengeni web app. Keep a scope the browser sent; stock UIs send personal in a private chat and workspace in a shared one. With shared chats, forward the body unchanged. Message rules for POST sessions/{sid}/events (user.message), steer and composer-draft/submit: reject mcpCredentialUpdates, and always refuse POST sessions/{sid}/mcp-credentials/rotate and session-imports (imported history is stored as genuine transcript, so only your server may write it). If you fix the model, overwrite model, reasoningEffort, and latencyMode with your values rather than dropping them. Your server may add modelContext and mcpCredentialUpdates itself. The modelContext the browser sends on these bodies, and on each entry of POST sessions/{sid}/realtime/{rid}/sync, is the browser’s unverified claim: validate, replace or drop it before forwarding if your product relies on it. Admitting work. If your product bills, rate-limits or otherwise admits agent work, check every request that starts it: the messages above, approval decisions and human-input answers (user.approvalDecision, user.humanInputResponse on events), POST sessions/{sid}/control with action: "resume", POST sessions/{sid}/retry (also drop its model, reasoningEffort and latencyMode if you fix the model), and POST sessions/{sid}/queue/{turnId}/steer. Key your own bookkeeping on the request’s clientEventId (idempotencyKey on create): Opengeni accepts an action once per key and answers a repeat with the first outcome, so when the upstream call fails or answers 408 or 5xx you can safely send the same body once more.

Headers

Send these upstream, and nothing else from the browser:
Return upstream status codes, error bodies, and the Content-Type, Content-Length, Content-Disposition, Content-Range, Accept-Ranges, ETag, Last-Modified, Retry-After, Content-Security-Policy, Cross-Origin-Resource-Policy and x-opengeni-* headers unchanged; the SDK reads them. Add Cache-Control: no-store and X-Content-Type-Options: nosniff, and Content-Security-Policy: sandbox when upstream sends none. For cross-origin browser calls, forwarding headers is not enough: set Access-Control-Expose-Headers from OPENGENI_BROWSER_RESPONSE_HEADERS, exported by @opengeni/sdk and @opengeni/sdk/browser. Set Access-Control-Allow-Headers from OPENGENI_BROWSER_REQUEST_HEADERS (plus your product’s own headers). For example:
A non-JavaScript backend can generate its configuration from that export at build time rather than maintaining a copied list. Preserve the history metadata even on same-origin relays: Has-More, cursors, coverage and Conversation-Filter are protocol data, not optional diagnostics. The SDK logs one actionable warning per client if required history headers are missing or unreadable (it cannot distinguish CORS filtering from an older API that did not send them). Do not replace a working exposure list with * on credentialed requests. To set the user’s permissions from your own roles, add "membership":{"permissions":["workspace:read","sessions:create","sessions:read"]} to the actor JSON. Opengeni makes the user’s workspace grant exactly that set before authorizing the request; see External users.

Security rules

  • Authenticate the user on every request and derive the workspace and user id on the server.
  • Reject any {ws} other than the resolved one.
  • Reject path segments that decode to empty, . or .., or contain /, \ or control characters, and percent-encode each segment again when you forward it.
  • Apply your CSRF protection to every method except GET and HEAD.
  • Cap request bodies you parse (1 MiB is plenty) and don’t log bodies or keys.
  • Stream request bodies, responses and SSE unbuffered, and close the upstream request when the browser disconnects.
  • Store each tenant’s workspace id. Create it once with POST /v1/workspaces/external (the SDK’s ensureWorkspace). Users are added to it on their first request.

Django example

Run it under an ASGI or threaded server so open event streams don’t block other requests.