Security best practices

Your API key is a long-lived credential with full access to your workspace. Anyone who has it can make requests on your behalf — and be billed to your account — until the key is deleted. These practices keep it that way only for you.

Never ship an API key in client code

Anything you ship to users can be inspected: browser JavaScript, Android APKs, iOS bundles, and game builds are all trivially unpacked, and TLS does not help — the key is extracted from the app itself, not the network. Treat any credential that has ever been in a client build as compromised: delete the key in Inworld Portal and create a new one.

API keys belong on servers you control:

• Store them in a secret manager, or as environment variables read at runtime.
• Keep them out of source control, build artifacts, and logs.
• Use separate keys per environment (development, staging, production), so revoking one does not take down the others.

Two safe patterns for client apps

Pattern A: proxy through your backend

The client talks only to your backend; your backend holds the API key and calls Inworld:

Browser / mobile app  →  your backend (holds the key)  →  api.inworld.ai

This is the simplest model, gives you a natural place for your own auth, quotas, and logging, and no Inworld credential ever leaves your infrastructure. The trade-off is an extra network hop on every request — for streaming audio, that can matter.

Pattern B: mint a token, connect directly

For latency-sensitive streaming (TTS, STT, Realtime), let the client talk to Inworld directly — but never with the API key. Your backend authenticates the user, mints a short-lived token with the key, and hands the token to the client:

Client  →  your backend: "give me a token"     (your own auth here)
Backend →  Inworld: mint token with API key
Client  →  api.inworld.ai with the token       (direct, low latency)

Two token types support this, in order of preference:

• One-time tokens — single-use, short-lived (15 minutes by default). Each token authenticates exactly one connection or request, so a leaked token that was already used is worthless, and an unused one dies within minutes. Mint one per connection attempt.
• Session tokens (deprecated) — multi-use JWTs that live for a few hours, still required for Realtime sessions. A leaked session token is usable until it expires — and it carries its parent key's full permissions — so keep its exposure narrow and mint it from the narrowest key that fits (for example, a Realtime-only key).

Your token endpoint is the security boundary in this pattern: authenticate your users before minting, and mint per user session — never serve one cached token to everyone.

If a credential leaks

1. API key — delete it in Portal → API Keys and issue a new one. Deleting the parent key also invalidates every token minted from it.
2. Token — one-time tokens expire in minutes and die on first use; session tokens expire on their own. If you can't wait, delete the parent API key.
3. Review usage for activity you don't recognize.