Introduction

If you are wiring a realtime avatar into an app, the security model matters as much as the rendering path. The hard part is not just “can I call the API?” It is deciding what credential should exist in which trust boundary: server, browser, iframe, or client device.

In practice, developers usually choose between three patterns: a long-lived API key, a short-lived JWT, or some form of signed token. They are not interchangeable. Each one answers a different question:

• Is this caller allowed to manage resources on my account?

• Is this browser session allowed to use a specific avatar or embed?

• How do I prevent a token from becoming a reusable bearer secret forever?

By the end, you should be able to decide which credential belongs on your backend, which belongs in a browser-facing flow, and where to use short-lived signed tokens instead of exposing anything sensitive. I will also show where Protoface fits cleanly into that model without forcing you to punch holes in your security design.

First principles: what each token type is actually for

Let’s define the terms precisely.

API key usually means a long-lived opaque secret that identifies your application or account. It is excellent for server-to-server calls because it is simple, revocable, and easy to rotate. It is also dangerous in any untrusted environment because it is typically a full bearer credential: whoever has it can use it until you revoke it.

JWT is a signed claims container. It is not inherently “more secure” than an API key; it is just more expressive. A JWT can encode expiration, audience, subject, tenant, permissions, and session metadata. The value is that the receiver can verify the signature and trust the claims without a database lookup on every request. The cost is more implementation complexity and more room for mistakes if you treat JWTs like magic.

Signed token is a broader category. It often means a token generated by your backend, cryptographically signed, and scoped to a narrow use case. A signed token may be a JWT, but it does not have to be. For realtime avatar signage, the key property is usually not the format; it is the scope and lifetime.

The practical question is not “Which token is best?” It is “What is the smallest credential that can safely authorize this exact action for this exact duration?”

When an API key is the right tool

API keys are the right choice for privileged backend operations: create avatars, list sessions, inspect usage, rotate resources, or create ephemeral session credentials on behalf of a user. If the operation touches your Protoface account state, put it behind your server and use the REST API with your API key there.

This is the normal pattern:

1. Your app backend authenticates the user.

2. Your backend calls the Protoface API with an API key.

3. Your backend returns only a narrow, user-specific result to the client.

That separation gives you auditability and limits blast radius. If a browser is compromised, the attacker should not discover your account-level API key.

A minimal server-side call looks like this:

curl -X POST https://api.protoface.com/v1/avatars \
-d '{"name":"support-agent"}'

curl -X POST https://api.protoface.com/v1/avatars \
-d '{"name":"support-agent"}'

curl -X POST https://api.protoface.com/v1/avatars \
-d '{"name":"support-agent"}'

The exact path and payload shape depend on the endpoint; the point here is that the authorization lives only on the trusted side. Keep the key in your secret manager, not in frontend env vars, not in mobile binaries, and not in any code path that ships to users.

When a JWT is the right tool

JWTs are useful when you need a stateless, time-bounded assertion about a user or session. Typical examples:

• “This logged-in user may join this avatar session.”

• “This tenant may access only avatar X.”

• “This session expires in 10 minutes and belongs to device Y.”

For realtime systems, JWTs are attractive because they can be validated at connection time without keeping a server-side session record for every handshake. That matters when the client is opening a WebRTC or streaming session and you want the authorization decision to be cheap.

But JWTs are not a free pass. If you stuff too many claims into them, you create brittle authorization logic. If you make them long-lived, you recreate the same risk profile as an API key. If you do not validate audience, expiry, issuer, and signing algorithm strictly, you have a security bug.

A typical pattern is to mint a short-lived JWT on your backend and hand that to the client only for establishing a specific realtime session:

from datetime import datetime, timedelta, timezone

token = jwt.encode(claims, PRIVATE_KEY, algorithm="RS256")

from datetime import datetime, timedelta, timezone

token = jwt.encode(claims, PRIVATE_KEY, algorithm="RS256")

from datetime import datetime, timedelta, timezone

token = jwt.encode(claims, PRIVATE_KEY, algorithm="RS256")

The important part is not the library call; it is the semantics. The JWT should be short-lived, purpose-built, and verifiable by the service that needs it. If the client only needs to prove “I am allowed into this one avatar session,” do not give it broader API authority than that.

Signed tokens for realtime avatar embeds

For browser-facing embeds, a signed token is often the best fit because you can scope it very narrowly to a single embed, a single origin set, and a small window of time. That is especially relevant for realtime avatar signage where you want the browser to connect directly without ever exposing a long-lived secret.

The security model should look like this:

• The browser never sees your API key.

• Your backend generates a short-lived signed token or signed embed URL.

• The token authorizes only the specific embed/session it was minted for.

• The service enforces expiry, origin allowlisting, and rate limits.

This is the right pattern when you are embedding an interactive avatar on a website and you do not want to build your own backend relay just to protect a credential. It also maps well to customer-managed iframe embeds where the parent origin is allowlisted and the session can be constrained by duration and IP.

The main advantage of signed tokens over raw API keys in the browser is obvious: compromise of one token should not compromise your account. The less obvious advantage is operational. You can make the token represent exactly one session policy instead of reimplementing a general-purpose auth system in frontend code.

The main gotcha is replay. If a token can be reused across origins or after logout, you have not really scoped it. Make sure the token includes enough context to bind it to the right user, origin, and time window, and make sure the receiving service enforces those constraints.

How to think about it in a realtime avatar system

Realtime avatar signage has two distinct planes:

Control plane: create avatars, manage sessions, inspect billing, and configure defaults. This belongs on your backend and uses an API key.

Data plane: the live session itself, where audio, video, and timing-sensitive state flow between client and service. This should use a short-lived, narrowly scoped credential, usually a signed token or JWT.

That split is especially important because realtime avatar flows are often attached to voice agents. The agent may already be doing streaming speech-to-text, LLM inference, and text-to-speech. Adding video sync means one more moving part, but it should not mean one more secret leaked to the browser.

A useful rule of thumb:

• If the operation mutates global account state, use an API key server-side.

• If the operation authorizes one user to enter one session, use a short-lived JWT or signed token.

• If the operation runs in the browser, assume the credential will be copied, inspected, and replayed unless you design otherwise.

Another practical gotcha is token refresh. WebRTC or other persistent connections may outlive a five-minute token. Decide up front whether the session should reconnect with a fresh token, or whether the server should keep the session alive only while the original authorization remains valid. Do not leave this implicit.

Where Protoface fits

Protoface gives you both sides of the split cleanly. Use the REST API and the Python SDK from your backend when you need to create avatars or manage sessions. Use the browser-safe iframe embed when you want an interactive avatar on a site without exposing an API key at all.

For the backend path, the Python SDK keeps the control-plane code straightforward:

from protoface import Client

)

from protoface import Client

)

from protoface import Client

)

For browser embedding, the important part is that the client-side experience does not require your secret. The iframe model is the correct answer when you want a quick, low-risk integration and you do not want to build and secure a token broker yourself. If you are using a voice-agent stack, the LiveKit plugin path is also useful because it keeps the avatar synchronized with the agent rather than treating video as a separate afterthought. See the relevant examples in the repository and docs if you are integrating that way: Python SDK, docs, and the quickstarts linked from the project README.

Conclusion

The decision is simpler than it first appears:

• API key for trusted backend control of your account and resources.

• JWT for short-lived, claim-based authorization when the receiver needs to verify who the caller is and what they may do.

• Signed token for narrowly scoped browser or session access, especially for realtime embeds and ephemeral connections.

For realtime AI avatar signage, the safest architecture is usually API key on the server, short-lived token at the edge, and nothing sensitive in the browser. That gives you a clean trust boundary without making the system harder to operate than it needs to be.

If you are implementing this now, start with the docs, wire the backend control plane first, and only then expose the smallest possible client-facing token. The examples and integration notes at docs.protoface.com are the right place to validate endpoint details before you ship.