Authentication

The SDK talks to four backend endpoints — agent-session (LiveKit token), appearance, form-responses, and events — and all four support two auth modes.

Public browser embed (default, recommended)

Pass only agentSlug. No key is sent. The backend authorizes the request by matching its Origin header against the agent’s Allowed Origins list (configured per character in the dashboard). This is exactly how the embeddable widget works.

createVoiceAgent({ agentSlug: "support-bot" });

To allow a new site, add its origin to the character’s allow-list in the dashboard under Characters → [your character] → Allowed Origins. Entries are URL prefixes:

https://acme.com
https://staging.acme.com

Server / trusted mode

Pass a secret key (sk_…). It’s sent as the x-api-key header, which bypasses origin gating. Use it for:

• Node / server-side session minting.
• First-party apps on locked-down origins.

createVoiceAgent({
  agentSlug: "support-bot",
  apiKey: process.env.OSHARA_API_KEY,
  fetch, // Node 18+ has global fetch; pass one on older runtimes
});

⚠️ Never ship a secret key in browser JS

Anything in your client bundle is readable by anyone who opens devtools. If you set apiKey while running in a browser, the SDK logs a warning. For public sites, use the default origin-gated mode instead.

Quick reference

// Browser (public) — origin allow-list authorizes the request
createVoiceAgent({ agentSlug: "support-bot" });
 
// Node / server — secret key bypasses origin gating
createVoiceAgent({
  agentSlug: "support-bot",
  apiKey: process.env.OSHARA_KEY,
  fetch,
});