Conceptual Overview

The Orga Architecture

At a high level, Orga AI connects your clients (React or React Native apps), through your server proxy, to the Orga backend. The Server SDK issues secure credentials, and the Client SDK sets up a real-time WebRTC session.

The 3 Core Orga API Endpoints

The Role of SDKs

Server SDK (Node.js)

The Server SDK abstracts the secure setup required to start any Orga session:

• Exchanges your long-lived API key for a short-lived ephemeral token
• Fetches ICE server configs for WebRTC connectivity
• Serves as a secure proxy endpoint for your clients

This helps you keep your production API keys server-side while your clients use short-lived credentials.

🛡️ Coming soon: Additional SDKs for Python, Go, and more.

Client SDKs (React & React Native)

The Client SDKs abstract the complexity of WebRTC and manage:

• Audio/video streaming
• Session negotiation (SDP exchange)
• DataChannel event handling

Available for:

• React SDK
• React Native SDK

🧠 Under Development:
More client SDKs for additional frameworks (e.g., Vue, iOS, Android) are in progress.

Core Concepts

This section explains the foundational ideas behind Orga AI’s real-time system.

Sessions

A session represents a real-time WebRTC connection to Orga AI for multimodal communication (audio-only or audio+video).

Typical Lifecycle

1. Server-side
   • Exchange API key for an ephemeral JWT (POST /v1/realtime/client-secrets)
   • Retrieve ICE servers (GET /v1/realtime/ice-config)
2. Client-side
   • Start the live call with (POST /v1/realtime/calls)
3. During session
   • Send/receive data, media, and events over WebRTC DataChannels

Authentication

Use ephemeral JWTs issued through your backend proxy to protect your primary API key.

Proxy responsibilities:

• Request ephemeral tokens from /v1/realtime/client-secrets
• Fetch ICE configuration
• Return both values to the client

Example (using the Server SDK)

import { OrgaServer } from "@orga-ai/server-sdk";
 
const orga = new OrgaServer({
  apiKey: process.env.ORGA_API_KEY,
  userEmail: process.env.ORGA_USER_EMAIL,
});
 
const clientCredentials = await orga.getSessionConfig();

This single call handles token issuance and ICE configuration.

ICE Configuration and WebRTC

Orga AI uses WebRTC for low-latency, bidirectional communication.
ICE servers (STUN/TURN) ensure reliable connectivity across different network conditions.

The Server SDK fetches ICE via GET /v1/realtime/ice-config, and the Client SDK automatically embeds it in the WebRTC setup.

DataChannel Events

Once connected, Orga AI sends events over WebRTC DataChannels in real time.

Secure Proxy Setup

To prevent API key exposure, implement a simple backend route to generate short-lived client credentials.

Your backend proxy (or Server SDK instance) should:

1. Retrieve an ephemeral token via /v1/realtime/client-secrets
2. Fetch ICE configuration via /v1/realtime/ice-config
3. Return both to the client

The client then starts the actual session via /v1/realtime/calls.

You can think of it as:

Example (Node.js/Express):

import express from "express";
import { OrgaAI } from "@orga-ai/server-sdk";
 
const app = express();
const orga = new OrgaAI({ 
  apiKey: process.env.ORGA_API_KEY, 
  userEmail: process.env.ORGA_USER_EMAIL 
  });
 
app.get("/api/orga/credentials", async (req, res) => {
  const credentials = await orga.getSessionConfig();
  res.json(credentials);
});
 
app.listen(3000, () => console.log("Proxy running on http://localhost:3000"));

Your client can then initialize the SDK using your proxy endpoint:

import { OrgaAI } from "@orga-ai/react";
 
const orga = OrgaAI.init({
  fetchSessionConfig: async () => {
    const response = await fetch('/api/orga/credentials');
    const { ephemeralToken, iceServers } = await response.json();
    return { ephemeralToken, iceServers };
  },
});

Summary

• Server SDK → Handles authentication and proxy setup
• Client SDK → Establishes real-time calls and data streaming
• Direct API calls → For advanced control or custom setups

🧭 Start with SDKs for simplicity.
Drop down to the raw API only when you need low-level customization.

Next Steps