Architecture

The Orga Node SDK (@orga‑ai/node) operates as the secure backend layer in the Orga AI ecosystem.
It sits between your client applications and the Orga Cloud API, exchanging permanent API keys for short‑lived credentials used in real‑time sessions.

Understanding these layers helps you design scalable, secure integrations.

Layers at a Glance

Division of Responsibilities

How It Works

When a client requests credentials from your backend:

1. Your backend route calls orga.getSessionConfig().
2. The Node SDK internally handles both Orga API calls (for token + ICE).
3. It responds to the client with a consolidated SessionConfig object.
4. The client uses this data to start its WebRTC connection with Orga Cloud.

🔒 Security Principle:
The Orga API key is never shared with clients. Only temporary tokens are sent over the wire.

SDK Class Responsibilities

OrgaAI Class

The core class of the SDK encapsulates all operations needed for secure server‑side communication.

Key Concepts

• Ephemeral tokens — short‑lived JWTs issued using your API key; they expire quickly and are safe to distribute to clients.
• ICE configuration — STUN/TURN servers provided by Orga to establish peer connections through NAT/firewalls.
• Timeouts — All requests are automatically timed out (default 10s) for stability.
• Debug logs — Enable debug: true to print request flow information in development.

Example Data Flow

Frontend (React / RN)
    ↓  /api/orga-client-secrets
Backend (Node SDK)
    ↓  POST /v1/realtime/client-secrets
    ↓  GET  /v1/realtime/ice-config
Orga Cloud
    ↑  { ephemeralToken, iceServers }
Backend
    ↑  returns SessionConfig to client
Frontend
    ↑  starts WebRTC session

Design Principles

Environment Requirements

Example Integration Overview

import express from "express";
import { OrgaAI } from "@orga-ai/node";
 
const router = express.Router();
const orga = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
  userEmail: process.env.USER_EMAIL!, // will be optional soon
  debug: false,
});
 
router.get("/api/orga-client-secrets", async (_req, res) => {
  try {
    const data = await orga.getSessionConfig();
    res.json(data);
  } catch (err) {
    console.error("Orga error:", err);
    res.status(500).json({ error: "Internal server error" });
  }
});
 
export default router;

import { NextResponse } from "next/server";
import { OrgaAI } from "@orga-ai/node";
 
const orga = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
  userEmail: process.env.USER_EMAIL!,
});
 
export async function GET() {
  try {
    const config = await orga.getSessionConfig();
    return NextResponse.json(config);
  } catch (error) {
    console.error("Orga error:", error);
    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
  }
}

import { OrgaAI } from "@orga-ai/node";
 
export const handler = async (req, res) => {
  const orga = new OrgaAI({
    apiKey: process.env.ORGA_API_KEY!,
    userEmail: process.env.USER_EMAIL!,
  });
 
  try {
    const creds = await orga.getSessionConfig();
    return res.status(200).json(creds);
  } catch (e) {
    return res.status(500).json({ error: e.message });
  }
};

Next Steps

• Quick Start → Build a secure backend route in minutes.
• API Reference → Reference for the OrgaAI class.
• Troubleshooting → Troubleshooting guide.