Node SDK architecture
@orga-ai/node acts as the secure middle tier between your frontend and Orga Cloud. It owns the only copy of your permanent API key, turns that into short-lived credentials, and responds to client requests with everything they need to start WebRTC sessions.
Layers
| Component | Responsibility |
|---|---|
| Client SDKs | Ask your route for { ephemeralToken, iceServers }. |
| Node SDK | Holds API key, calls Orga Cloud, returns consolidated SessionConfig. |
| Orga Cloud | Issues tokens and TURN/STUN credentials, validates usage. |
Request lifecycle
- Client request – React/React Native calls your proxy route (typically
/api/orga-client-secrets). - Token exchange – Node SDK posts your API key to Orga; receives an ephemeral token that expires in minutes.
- ICE fetch – With that token, the SDK immediately fetches TURN/STUN servers so the client doesn’t have to make extra calls.
- Response – The SDK packages everything into a
SessionConfigobject. The client uses it to call/v1/realtime/calls.
Inside the OrgaAI class
| Method | Visibility | Purpose |
|---|---|---|
constructor(config) | public | Stores API key, timeout, base URL, and debug flag. |
getSessionConfig() | public | Primary API: orchestrates token + ICE fetches and returns { ephemeralToken, iceServers }. |
fetchEphemeralToken() | internal | Makes the POST request to /v1/realtime/client-secrets. |
fetchIceServers() | internal | Makes the GET request to /v1/realtime/ice-config using the ephemeral token. |
Because it’s a tiny surface area, you can reuse a single instance across requests (e.g., module-level singleton in Express) and avoid re-reading env vars every time.
Deployment considerations
- Rate limiting / auth – Layer your own authentication or quota controls before calling
getSessionConfig(); the SDK focuses solely on Orga communication. - Timeouts – Default is 10s. Increase it for high-latency regions or wrap calls in your own retry logic.
- Observability – Enable
debug: truein non-production environments to log the credential exchange; in prod, log request IDs +conversation_idbut never tokens. - Edge vs serverful – Works in Node 18+ and edge runtimes that support
fetch. On very tight memory footprints, instantiate theOrgaAIclient lazily to avoid state leakage.
Related reading
- Node SDK introduction for motivation and capabilities.
- Secure backend proxy how-to for a concrete implementation path.
- React architecture explanation to see how clients consume the session config you return.
Last updated on