Build a secure backend proxy

Every Orga client needs short-lived credentials before starting a real-time session. This guide walks you through creating a backend endpoint that exchanges your API key for ephemeral tokens and ICE servers, keeping your long-lived credentials secure on the server.

Prerequisites

• Completed the environment variable guide so ORGA_API_KEY is available on your server.
• Node.js 18+ (for the Orga Node SDK) or another backend runtime that can make HTTPS requests.
• An HTTPS-accessible server or API route that your clients can call.

1. Initialize the Node SDK

Start by creating an OrgaAI client instance. The SDK handles retries, logging, and TypeScript types for you:

import { OrgaAI } from '@orga-ai/node';
 
export const orga = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
  debug: process.env.NODE_ENV !== 'production',
});

2. Create the proxy route

Create an endpoint that returns both the ephemeral token and ICE servers. Here are two common implementations:

import express from 'express';
import cors from 'cors';
import { orga } from './libs/orga';
 
const app = express();
app.use(cors({ origin: ['http://localhost:3000', 'https://app.yourdomain.com'] }));
 
app.get('/api/orga-client-secrets', async (_req, res) => {
try {
  const config = await orga.getSessionConfig();
  res.json(config); // { ephemeralToken, iceServers }
} catch (error) {
  console.error('Orga proxy error', error);
  res.status(500).json({ error: 'Failed to fetch session config' });
}
});
 
app.listen(5000, () => console.log('Proxy listening on http://localhost:5000'));

import { NextResponse } from 'next/server';
import { orga } from '@/libs/orga';
 
export async function GET() {
try {
  const config = await orga.getSessionConfig();
  return NextResponse.json(config);
} catch (error) {
  console.error('Orga proxy error', error);
  return NextResponse.json({ error: 'Failed to fetch session config' }, { status: 500 });
}
}

3. Secure the endpoint

Before deploying to production, add these security controls:

4. Test your endpoint

Test the proxy to make sure everything works:

1. Start your server (pnpm dev, node server.ts, or next dev).
2. Make a request to your endpoint:

curl http://localhost:5000/api/orga-client-secrets

3. Verify the response includes both the ephemeral token and ICE servers:

{
  "ephemeralToken": "eyJhbGciOi...",
  "iceServers": [{ "urls": "stun:stun1.l.google.com:19302" }, { "urls": ["turn:turn.orga-ai.com:3478"], "username": "...", "credential": "..." }]
}

If you set debug: true, the server logs should show:

[OrgaAI] Fetching session config...
[OrgaAI] Fetched ephemeral token: eyJhbGc…
[OrgaAI] Fetched ICE servers: 3

5. Configure clients to use the proxy

Update your client applications to fetch credentials from your proxy endpoint. Here’s how to configure it in React:

OrgaAI.init({
  fetchSessionConfig: async () => {
    const res = await fetch('/api/orga-client-secrets', {
      headers: { Authorization: `Bearer ${user.accessToken}` },
    });
    if (!res.ok) throw new Error('Failed to fetch session config');
    return res.json();
  },
});

React Native apps work the same way—just point fetch to your production API URL: https://api.yourdomain.com/orga-client-secrets.

Production deployment

Before going live, keep these considerations in mind:

• Monitor for errors – Watch for HTTP 4xx or 5xx responses. A spike in errors usually means an expired API key or network connectivity issues.
• Rotate keys regularly – Update ORGA_API_KEY periodically for security. Since only your proxy uses it, rotating is straightforward.

Once your proxy is deployed, your client applications can safely start Orga sessions without ever handling your long-lived API key.