API keys

An API key is your workspace's long-lived credential. Everything else — session tokens and one-time tokens — is minted from an API key, and dies with it.

API keys live on your servers, never in client code. See Security best practices for the rules and the safe patterns for browsers, mobile, and games.

Getting an API key

To get an API key from the Portal:

1. Log in to Inworld Portal.
2. Click API Keys on the bottom left sidebar.
3. Click Generate new key to generate a new API key.
4. Copy the API key.

You can also specify for each API key whether it has write permissions to:

• Voice API, which enables the API key to be used for POST, PATCH, and DELETE endpoints (clone voice, update voice, delete voice). GET endpoints only require read permissions.
• Router API, which enables the API key to be used for POST, PATCH, and DELETE endpoints (create router, update router, delete router). GET endpoints only require read permissions.

These permissions do not impact other APIs (such as Text-to-Speech and LLM).

Alternatively, the Inworld CLI mints a key without leaving the terminal — this also works for AI coding agents:

npm install -g @inworld/cli
inworld login
inworld workspace add-key --name my-key   # add --write to also allow Voice and Router write endpoints
inworld workspace select-key              # make the new key the active one
inworld auth print-api-key                # print the API key for the Authorization header

--write only affects write endpoints of the Voice API and Router API — other APIs (such as Text-to-Speech and LLM) are not impacted.

Key permissions

What a key can reach:

• Standard keys cover the platform APIs — TTS, STT, LLM, and read access to Voices and Router configuration.
• Write permissions to the Voice API and Router API are opt-in toggles on the key: they gate POST, PATCH, and DELETE endpoints (cloning, updating, and deleting voices or router configs). GET endpoints only need read permissions, and other APIs are unaffected. You can edit these toggles on an existing key at any time.
• Realtime-only keys (below) cover only the Realtime API.

Tokens minted from a key inherit exactly its permissions.

Realtime-only API keys

A Realtime-only key is a credential built specifically for the Inworld Realtime API. Use it for voice agents that connect over WebSocket or WebRTC — it follows the least-privilege rule: if that key leaks, only Realtime is exposed.

It covers:

• Realtime sessions over WebSocket and WebRTC
• Streaming audio in and out within a realtime session
• Speech, language, and voice generation the Realtime API performs for you

For other Inworld APIs, use a Standard key.

To create one: in Inworld Portal open API Keys, click Generate new key, and choose Realtime-only as the key type.

Managing keys

• Deleting a key immediately invalidates it — and every token minted from it. That makes the key your revocation lever: see Security best practices.
• Use separate keys per environment and per integration, so one revocation has a small blast radius.
• Usage is attributed per key in the usage dashboard.