Introduction

When you add an in-app AI avatar, the hard part is rarely rendering the face. The hard part is deciding who can create a session, which tenant that session belongs to, and what the avatar is allowed to say and do once it’s live. If you get multi-tenant access wrong, you end up with API keys exposed in browsers, cross-tenant data leaks, unbounded usage, and support incidents that are much more painful than the original feature.

This post is about designing secure multi-tenant access for realtime avatar assistants: how to separate tenants, issue short-lived access, enforce policy at the edge, and keep your backend as the authority. I’ll focus on the mechanics you can actually implement in a voice agent or embedded web experience, with examples using Protoface as the avatar layer.

Model the problem as identity, tenancy, and capability

Before you write code, define three distinct concepts:

• Identity: the end user, or the operator/admin acting on behalf of a tenant.

• Tenancy: the account, workspace, customer, or organization boundary that owns avatars, sessions, usage, and billing.

• Capability: the exact action being authorized, such as “create a session for avatar X,” “attach voice profile Y,” or “read usage for tenant Z.”

Most security bugs happen when these are collapsed into one “logged-in user” concept. For multi-tenant AI assistants, they should stay separate all the way down to the API call. Your backend should translate a user’s identity into a tenant-scoped capability, then mint a request that only permits that one action.

Two practical rules follow from that:

1. Never expose your master API key to untrusted clients. If the browser or mobile app can see it, you’ve already lost tenant isolation.

2. Every session should be attributable to a tenant at creation time. Don’t infer tenant ownership later from metadata alone; enforce it when the session is minted.

Put the browser on a leash: backend-issued, short-lived access

For web clients, the safest pattern is simple: the browser authenticates to your app, your backend verifies tenant membership, and your backend calls the avatar service using its own secret credentials. The client never sees the provider API key. This matters even more for realtime systems because a session is not a single HTTP request; it’s a long-lived stream, often over WebRTC, with signaling, media, and control messages that can persist for minutes.

For a typical flow:

1. User signs into your app.

2. Your backend resolves their tenant and role.

3. Your backend creates an avatar session for that tenant.

4. Your backend returns only the minimum session data needed by the client to connect.

5. The client opens the realtime channel and starts exchanging audio/video or control messages.

The important part is that the backend remains the policy enforcement point. The client is only a transport endpoint.

Enforce tenant context in the session, not in the UI

It is tempting to hide “dangerous” controls in the UI and assume that is enough. It isn’t. Multi-tenant access needs to be enforced in the server-side session record itself. Concretely, each session should carry at least:

• tenant ID

• creator identity

• avatar ID

• allowed voice or persona settings

• expiration time

• rate/usage budget, if applicable

That gives you a durable authorization boundary. If a request arrives later to mutate the session, you compare the caller’s tenant ID and permissions against the stored session tenant. If they do not match, the operation is rejected before it touches downstream realtime infrastructure.

For example, if your application supports customer-specific avatars, do not let one tenant pass arbitrary avatar IDs. Map tenant-owned avatars in your database and validate ownership server-side. The browser can request “the sales assistant,” but the backend decides which concrete avatar ID that means for that tenant.

Use ephemeral credentials and strict origin controls for embeds

Embedded experiences are where teams most often make mistakes. If you can add an avatar to any website, you need a strategy that does not depend on trusting the embedding page. The right approach is to keep secrets server-side and use a narrow, per-embed authorization model:

• allow only approved parent origins

• scope each embed to a specific tenant or customer

• limit duration and per-IP usage

• treat the embed as a constrained session broker, not a general-purpose client

That gives you a practical defense against key leakage and abuse. Even if a customer copies the iframe snippet, it should only work from approved origins and within the limits you set.

If you are implementing the policy yourself, the key thing to remember is that origin checks are necessary but not sufficient. They reduce misuse from the browser, but your backend still needs to mint a tenant-bound session and enforce expiry on the server side. Otherwise, a copied token just becomes a reusable bearer credential.

Rate limits and billing need to be tenant-aware

Realtime avatar systems are usage-driven: session time, media quality, and model selection all affect cost. In a multi-tenant environment, usage accounting is part of authorization, not just finance. A tenant that is over budget should not be able to keep creating sessions indefinitely.

Implement limits at several layers:

• Request rate: limit how often a tenant can create or mutate sessions.

• Concurrency: cap the number of active sessions per tenant.

• Duration: enforce maximum session lifetimes.

• Origin/IP: for browser-facing flows, constrain where requests may come from.

These controls should be checked before expensive realtime resources are allocated. That prevents a burst of invalid requests from turning into a billable workload.

Example: mint a tenant-scoped session from your backend

The exact request fields depend on your integration, but the pattern is always the same: your backend authenticates with the service, attaches tenant context, and returns only what the client needs.

curl -X POST https://api.protoface.com/sessions \
}'

curl -X POST https://api.protoface.com/sessions \
}'

curl -X POST https://api.protoface.com/sessions \
}'

In practice, you would not let the browser call this directly. Your app server would do it after checking the authenticated user’s tenant membership.

Example: backend code with the Python SDK

If you prefer to keep the orchestration in Python, the SDK is a good fit for creating and managing avatars and sessions from your app server. Keep the auth key in your server environment only.

from protoface import ProtofaceClient

return {"session_id": session.id, "connect_url": session.connect_url}

from protoface import ProtofaceClient

return {"session_id": session.id, "connect_url": session.connect_url}

from protoface import ProtofaceClient

return {"session_id": session.id, "connect_url": session.connect_url}

The important architectural point is not the exact method names; it is that the SDK is used server-side to bind the session to a tenant before any client ever sees connection details. Check the docs for the exact request/response schema.

How this looks inside a voice agent pipeline

If you are adding an avatar to an existing realtime voice agent, the integration point is usually the agent pipeline rather than the UI. The agent already has a stream of audio and text state; the avatar plugin turns that into a synchronized face. The security model does not change: your agent service still needs to know which tenant owns the current conversation and which avatar configuration is allowed for that tenant.

With the LiveKit plugin, for example, the agent process can attach an avatar once it has verified tenant context. The plugin handles the media synchronization; your code is still responsible for deciding whether that session may exist in the first place. That division of responsibility is what keeps one customer’s avatar from becoming another customer’s resource.

For implementation details and examples, use the plugin repo and docs rather than guessing at runtime behavior: GitHub organization and docs. If you’re using Pipecat instead of LiveKit, the same tenant-scoping principles apply in the video service layer.

Common mistakes to avoid

A few failure modes show up repeatedly:

• Frontend-held API keys: even “temporary” keys leak via logs, browser extensions, and copied snippets.

• Tenant inferred from the avatar name: names are not access control.

• No server-side expiry: clients can keep stale sessions alive or replay old tokens.

• Shared default avatar IDs: a global default often becomes a cross-tenant escape hatch.

• Unbounded session creation: a single bug or malicious client can create real cost.

The fix is to treat every session as a privileged resource. Creation, mutation, and teardown all need server-side checks against tenant ownership and policy.

Where Protoface fits

The cleanest way to implement this with Protoface is to keep the platform-facing operations on the server and expose only tenant-scoped session details to the client. The REST API and Python SDK are the natural choice for backend-minted sessions; the iframe embed is the right choice when you want a browser experience without exposing any API key at all. For developers integrating with a voice stack, the LiveKit plugin lets you attach the avatar at the agent layer while keeping tenant authorization in your own app.

In other words: your app decides who may create a session and which avatar they may use; Protoface handles the realtime avatar part. That boundary is the whole point. See the public docs for exact parameters and examples, and use the quickstarts when you want a concrete starting point.

Conclusion

Secure multi-tenant access for in-app AI avatars is mostly about disciplined boundary setting: keep secrets server-side, mint short-lived tenant-scoped sessions, enforce origin and rate limits where browsers are involved, and make session ownership explicit in your backend data model. If you do those things, realtime avatars become a manageable capability instead of a security exception.

If you’re building this now, start with the docs, pick the integration surface that matches your architecture, and wire tenant validation into session creation before you connect any media path. The earlier you make tenancy explicit, the less painful everything else becomes.