Introduction

When you add a realtime avatar to a voice agent, you are not just rendering video; you are coordinating a session that typically spans authentication, signaling, media transport, and application state. That makes session tokens a security boundary, not just a convenience. If a token leaks, an attacker may be able to create or join sessions, observe usage, or drive avatar behavior within whatever scope that token allows.

This post is about securing REST API session tokens in a realtime avatar application: where tokens should live, how to issue them safely, how to keep them out of browsers and logs, and how to limit blast radius when things go wrong. The examples use Protoface as the concrete reference point, but the patterns apply to any developer-facing realtime media API.

Separate API keys from session tokens

The first design rule is simple: never put your long-lived API key in client-side code. API keys are for server-to-server access against the management API, such as creating avatars or provisioning sessions. In Protoface, that means calls to api.protoface.com should be made from your backend with an Authorization: Bearer sk_live_... header, not from the browser.

Session tokens are different. They should be short-lived, narrowly scoped, and tied to a specific user action or realtime session. In a voice-agent app, the browser may need a token to connect to an avatar session or initialize a live media flow, but the browser should never learn the secret used to mint that token.

The practical split looks like this:

1. Your backend authenticates the user.

2. Your backend calls Protoface with the API key.

3. Protoface returns or accepts whatever session artifact is needed for the realtime connection.

4. Your backend sends only the minimal client-facing token or connection payload to the browser.

If you can’t explain why a given secret must be present in the browser, it probably shouldn’t be there.

Use short-lived, audience-bound tokens

The most important properties of a session token are expiration, audience, and scope. Expiration keeps stolen tokens from being useful for long. Audience binding prevents a token minted for one surface from being reused on another. Scope limits the actions a token can authorize: join this session, initialize this avatar, or fetch this specific embed configuration.

For realtime media apps, the failure mode is often subtle: a token is valid, but valid too broadly. For example, a token intended for a single user’s browser session should not be reusable to create unlimited sessions or to access another customer’s avatar. If your token format supports claims, use them. If the API returns opaque tokens, make sure the server-side minting endpoint enforces the equivalent constraints.

Expiration should be measured in minutes, not hours, unless you have a strong reason otherwise. For a conversational session, the user-facing connection can be refreshed or reissued if the session is still active. That gives you a small compromise window and also makes revocation easier: stop minting new tokens and the old ones age out.

A reasonable backend pattern is:

from datetime import datetime, timedelta, timezone

}

from datetime import datetime, timedelta, timezone

}

from datetime import datetime, timedelta, timezone

}

The exact token shape depends on the API and SDK. The point is the structure: short TTL, explicit audience, explicit scope, and a one-session mindset.

Keep token issuance on the server

The most common mistake is to expose a “create session” endpoint that proxies the raw API key or returns overly powerful credentials to the browser. Don’t do that. Your backend should be the only place that can mint or request session tokens from the management API.

A simple server-side flow using the Python SDK might look like this:

from protoface import ProtofaceClient

}

from protoface import ProtofaceClient

}

from protoface import ProtofaceClient

}

That pattern has a few security advantages:

• The API key stays in your secret manager or deployment environment.

• You can authenticate the user before issuing a token.

• You can apply business rules, quotas, and per-user limits before any realtime connection exists.

• You can add logging and abuse detection without exposing internals to the client.

If you’re using raw HTTP instead of the SDK, the same principle applies. The browser should never call the management API directly:

curl -X POST https://api.protoface.com/sessions \
-d '{"avatar_id":"avt_123","ttl_seconds":300}'

curl -X POST https://api.protoface.com/sessions \
-d '{"avatar_id":"avt_123","ttl_seconds":300}'

curl -X POST https://api.protoface.com/sessions \
-d '{"avatar_id":"avt_123","ttl_seconds":300}'

The response shape will depend on the API. In any case, treat the returned session token as sensitive, but not equivalent to the long-lived API key.

Protect the browser surface and the network path

Once a token is issued, the next question is how it reaches the browser. If the token is delivered over an authenticated HTTPS session, the transport is already protected in transit. The remaining risks are storage and exposure:

• Do not persist session tokens in localStorage unless you have a specific reason and understand the XSS trade-off.

• Prefer in-memory storage for the lifespan of the page session.

• If you must survive reloads, use an HTTP-only cookie issued by your backend, not a JavaScript-readable token.

• Never include tokens in URLs; query strings leak via logs, referrers, and copy/paste.

For realtime apps, the browser usually needs only enough information to establish the media session and negotiate signaling. That payload should be as small as possible. If you expose extra claims to the client, assume they will be inspected by a user and potentially reused.

Also pay attention to logs. It is common for reverse proxies, application middleware, and observability tools to accidentally capture request bodies or headers. Scrub Authorization, session tokens, and any embed secrets at the ingress layer. A secure token design is useless if your logs become the easier target.

Revocation, rotation, and abuse controls

Short-lived tokens reduce exposure, but you still need operational controls. At minimum, implement:

• Rotation: rotate API keys regularly and on staff changes, and keep separate keys per environment.

• Revocation: maintain the ability to stop issuing tokens for a user, tenant, or avatar immediately.

• Rate limiting: cap session creation by IP, account, and tenant to reduce token spraying and abuse.

• Replay protection: ensure a single-use token cannot be exchanged repeatedly if your flow allows that.

For a realtime avatar app, abuse tends to show up as session churn: many short-lived sessions, unusual geographic distribution, or repeated token requests against one avatar. Instrument those events. Session creation should be auditable, and your incident response should include a clean way to revoke the relevant key or disable the affected user path.

One useful operational trick is to make token issuance idempotent for a narrow window. If a browser retries because of a network hiccup, you can safely return the same still-valid session token rather than minting a new one every time. That reduces token sprawl and makes debugging easier.

How Protoface handles this in practice

Protoface’s developer surfaces are designed around this split between server-side authority and client-side session use. The REST API and Python SDK are the right place to create and manage avatars and sessions, authenticated with API keys that stay on your backend. For browser-embedded use cases, customer-managed iframe embeds avoid exposing any API key in the browser at all, which is the cleanest option when your product does not need direct client-side API access.

For LiveKit-based agents, the quickstart examples show the right pattern: your agent backend owns the sensitive credentials, then hands the frontend only the minimum session material needed to connect the avatar into the voice flow. If you are using Pipecat, the integration guide is useful for seeing how the avatar service is wired into the pipeline without leaking management credentials into the client.

The common thread is the same: keep the management plane on the server, keep session credentials short-lived, and keep browser exposure minimal. The surface you choose matters less than preserving that boundary.

Common mistakes to avoid

A few patterns come up repeatedly in reviews:

• Embedding the API key in frontend code or shipping it through a public config object.

• Using one long-lived token for every user and every environment.

• Passing session tokens through URLs or client-side analytics events.

• Failing to expire sessions when the user logs out or closes the app.

• Trusting the browser to enforce anything security-sensitive.

For realtime avatar apps, the last point is especially important. The browser is a presentation layer and a transport endpoint, not a trusted authority. Any decision that grants access to an avatar session, a voice model, or a paid quality tier should happen on the backend.

Conclusion

Securing session tokens in a realtime avatar app is mostly about disciplined boundary management: API keys stay server-side, session tokens stay short-lived, the browser gets only what it needs, and observability never captures secrets. If you adopt those rules early, you avoid most of the painful failure modes that show up once users start connecting live voice agents to avatars.

If you’re implementing this with Protoface, start with the docs at docs.protoface.com, wire the management API or Python SDK into your backend, and make token issuance part of your normal auth and rate-limit flow. That will give you a secure base for realtime avatars without turning your frontend into a secret store.