Introduction

When you add avatars to a realtime WebRTC app, the first 80% is easy: get video flowing, keep audio synchronized, and make sure the face animates from the agent’s speech. The last 20% is where production issues show up. Per-user avatar themes need to persist across devices and sessions without leaking between tenants. Metadata needs to travel with the session so you can restore preferences, route analytics, or personalize behavior, but that same metadata is also a common place to accidentally expose secrets.

This post focuses on two things developers usually need at the same time: how to model per-user avatar themes cleanly, and how to handle session metadata without turning your WebRTC surface into an attack path. By the end, you should be able to design a theme model that is stable, debuggable, and tenant-safe, and understand which data belongs in the browser, which belongs on the server, and which should never leave your backend at all.

Model avatar themes as preferences, not state

For avatar apps, “theme” usually means a small set of user-controlled presentation choices: avatar identity, clothing or color palette, facial style, background, maybe voice pairing, and sometimes motion intensity or expressiveness. Treat these as durable preferences attached to a user or account, not as ephemeral session state.

The distinction matters because realtime sessions are short-lived, but user preferences are not. If you store them in the session object itself, you’ll eventually run into race conditions when a user opens multiple tabs, joins from mobile and desktop, or switches from a preview avatar to a production persona.

A clean model usually looks like this:

• Canonical user profile: stable preferences stored in your database.

• Derived session config: a snapshot of the current theme applied when a session starts.

• Transient runtime overrides: things the user can change live, such as “make the background darker” or “use a more energetic speaking style.”

This separation gives you three useful properties:

• Idempotence: starting a new session from the same profile yields the same result.

• Auditability: you can inspect what was configured at session creation time.

• Recovery: if the WebRTC connection drops, you can rebuild the session from the stored profile rather than guessing what the user had selected.

Use a small, explicit theme schema

Keep the schema narrow. The more unstructured the theme object becomes, the harder it is to validate, cache, and safely pass through to clients. A practical theme payload might include identifiers and a few constrained options, not arbitrary nested blobs.

{
}

{
}

{
}

A few implementation notes:

• Use stable IDs for avatar assets rather than embedding URLs in the client.

• Validate enumerated fields server-side. Don’t trust the browser to send only approved values.

• Prefer defaults over nulls. A missing field should resolve predictably.

• Version the schema if you expect to evolve it. Even a simple theme_version field can save you later.

If you let users customize appearance heavily, separate “safe styling” from anything that affects rendering privileges. A background color is fine; a raw HTML fragment or arbitrary CSS class name is not. If the avatar is rendered in an iframe or embedded surface, the browser should never be allowed to inject unvalidated presentation code.

Session metadata: useful, but easy to misuse

Realtime avatar sessions often need metadata for routing and personalization: user ID, tenant ID, chosen avatar, locale, experiment bucket, conversation mode, or upstream agent context. The key is to understand that metadata is not secret storage. It is data attached to a session, and in many systems it may be visible to your own backend, logs, analytics pipeline, or debugging tooling.

That means you should classify metadata before you send it anywhere:

1. Safe to expose to the session: non-sensitive identifiers, feature flags, display preferences, locale, and short-lived correlation IDs.

2. Keep server-side only: API keys, internal tokens, personally sensitive user attributes, billing internals, and privileged routing rules.

3. Never serialize into client-visible payloads: anything that would create a security incident if copied into browser devtools, logs, or an iframe query string.

In practice, the most common mistake is overloading “metadata” as a dumping ground for whatever the backend knows. If a field is needed to make security decisions, keep it on your server and derive a separate, minimal session descriptor for the avatar layer.

Secure handling patterns for WebRTC avatar apps

WebRTC itself is not the security boundary; your application is. The media transport is encrypted, but the surrounding control plane still needs careful handling. A secure avatar app usually follows these rules:

• Use short-lived session credentials for client-side session establishment whenever possible.

• Never place API keys in the browser. That includes query strings, localStorage, embedded JavaScript, and iframe attributes.

• Whitelist origins if you expose an embed. An allowlist is safer than relying on a generic CORS policy alone.

• Separate identity from authorization. A user ID in metadata does not prove the caller is that user.

• Audit logs carefully. It is very easy to accidentally log bearer tokens, session secrets, or PII when debugging media setup.

Another subtle issue is state drift between the avatar control plane and your own application session. If the user changes themes in your app, update your source of truth first, then create or update the realtime session from that source. Don’t let the WebRTC client become the authoritative store for user preferences unless you are prepared to reconcile conflicts and replay updates.

For multi-tenant products, make sure every theme lookup is scoped by tenant and user. “Avatar 7” is not a globally unique concept unless your data model makes it so. Enforce tenant boundaries in your server API, not in the front end.

Practical request flow

A safe production flow typically looks like this:

1. The browser sends a normal authenticated request to your backend.

2. Your backend loads the user’s theme preferences and applies server-side policy checks.

3. Your backend creates or configures the realtime avatar session with only the minimal metadata needed for that session.

4. The browser receives a short-lived session handle or embed URL, not long-lived secrets.

5. The avatar connects over WebRTC and renders using the validated theme snapshot.

If you need a direct API example, keep it minimal and server-side:

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

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

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

The exact request fields depend on the API version, so use the docs for the canonical schema. The important part is the shape of the control flow: the browser never sees the secret key, and the metadata sent to the avatar layer is already stripped down to what that layer actually needs.

Where Protoface fits

This is exactly the sort of problem Protoface is meant to sit in the middle of: your app keeps ownership of user preferences and authorization, while the avatar runtime gets a clean session configuration. If you are integrating through the REST API or Python SDK, the pattern is the same—load theme data on your server, validate it, then create the session with only the minimal metadata required for rendering and agent behavior. The public docs at docs.protoface.com are the right place to check the exact session and avatar fields before wiring this into production.

If you are embedding an avatar in a site without a backend, use the customer-managed iframe approach rather than trying to improvise client-side auth. That setup is specifically designed so you do not expose API keys in the browser, while still letting you constrain the embed with parent-origin allowlists and rate limits. For applications built around LiveKit voice agents, the plugin path is equally straightforward: the avatar becomes a synchronized visual surface attached to the agent, but your own theme and metadata rules should still live in your app, not inside the media transport.

Implementation gotchas that are easy to miss

• Do not trust theme input from query strings. A theme can be user-facing, but it is still untrusted input.

• Normalize identifiers. If your theme lookup is case-sensitive in one place and not another, you will get inconsistent avatar selection.

• Keep secrets out of logs. Bearer tokens, signed URLs, and session handles should be redacted by default.

• Avoid overloading metadata with presentation data. If the avatar renderer only needs a palette name, do not send the entire user profile.

• Plan for fallback behavior. If a theme cannot be loaded, default to a known-safe avatar and palette rather than failing the session.

If you are using a plugin or SDK, remember that the transport library is not your policy layer. It can help create and synchronize sessions, but it should not decide whether a user is allowed to access another user’s avatar theme.

Conclusion

Per-user avatar themes are best treated as validated, versioned preferences that your backend owns, then projected into a short-lived realtime session. Metadata is useful for routing and personalization, but only if you keep it minimal and classify it correctly. The browser should receive only what it needs to render the session; anything sensitive stays server-side.

If you are building this now, start by defining a small theme schema, add server-side validation and tenant scoping, and audit every place session metadata can be logged or echoed back to the client. Then wire that model into your avatar layer and test the unhappy paths: missing theme, stale session, reconnect, and cross-tenant access attempts. For concrete API shapes and integration details, check the docs and the relevant quickstart or SDK repository when you are ready to implement.