Authentication
Authentication overview
How requests to Inworld APIs authenticate: API keys, session tokens, and one-time tokens.
The workspace API key is Inworld's root credential. Two types of short-lived tokens are created from it for code that must not hold the key itself. Use the table below to choose a credential. The API key authentication guide explains the exact credential format, header exceptions, and how to recover from errors.
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, choose Realtime-only keys, and revoke access.
API key authentication
Learn the header format, where it works, and how to use it.
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
Keep keys out of clients, use a proxy or tokens, and respond to leaks.