Authentication
Overview
How requests to Inworld APIs authenticate: API keys, session tokens, and one-time tokens.
Inworld has one root credential — the workspace API key — and two kinds of short-lived tokens minted from it for code that must not hold the key itself. Use the following matrix to choose a path. The API key authentication guide defines the exact credential representation, header exceptions, and error recovery.
Pick a credential
| Where your code runs | Credential | Use |
|---|---|---|
| Server or local development | API key | Copy the Base64 credential unchanged. Use Basic for direct HTTP requests and keep the key on your server. |
| Direct browser/mobile TTS, STT, or LLM client | One-time token | Your backend mints a token for each HTTP request or WebSocket connection attempt. |
| Direct browser/mobile Realtime client | Session token | Your backend mints a session token. Realtime does not accept one-time tokens. |
SDKs that reuse tokens across requests or reconnects need a refresh flow that supplies a fresh one-time token for every attempt, or a server proxy. See the existing TTS SDK session-token pattern for legacy integrations.
Client code never receives the API key. Your backend authenticates and authorizes the user before issuing a token, applies per-user limits, and returns only the token fields the client needs. Tokens inherit the parent key's permissions; use the narrowest suitable key. See Security best practices.
Guides
API keys
Create keys, set write permissions, Realtime-only keys, revocation.
API key authentication
The header, examples, where it works.
One-time tokens
Single-use, short-lived — the preferred client credential.
Session tokens
Deprecated multi-use JWTs — still used for direct client Realtime sessions.
Security best practices
Keys out of clients; proxy or token patterns; leak response.