Authentication
Overview
How requests to Inworld APIs authenticate: API keys, session tokens, and one-time tokens.
Every request to an Inworld API carries a credential in the Authorization header. There is one root credential — the workspace API key — and two kinds of short-lived tokens minted from it for code you can't trust with the key itself.
Pick a credential
| Credential | Header | Lifetime | Where it belongs |
|---|---|---|---|
| API key | Authorization: Basic <api-key> | Until you delete the key | Your servers only |
| One-time token — preferred for clients | Authorization: Bearer <token> | Minutes, single-use | Clients that make one connection per token |
| Session token — deprecated | Authorization: Bearer <jwt> | A few hours, multi-use | Realtime sessions, which one-time tokens can't cover yet |
Two rules cover most decisions:
- Server-side code authenticates with the API key directly. Simple, no minting step.
- Client-side code never sees the API key. Your backend mints a token and hands only the token to the client. Prefer one-time tokens: every token carries the key's full permissions, and a single-use, minutes-lived credential exposes them for at most one connection. Session tokens are deprecated; they remain for Realtime sessions, which one-time tokens can't cover yet. The reasoning and patterns are in 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 required for Realtime sessions.
Security best practices
Keys out of clients; proxy or token patterns; leak response.