API keys

An API key is your workspace's long-lived credential. Session tokens and one-time tokens are created from an API key. Deleting that key invalidates them too.

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

Getting an API key

To get an API key from the Portal:

1. Log in to Inworld Portal.

2. In the sidebar, under Manage, select API Keys.

   

3. Click Generate new key. In New API key, choose the key type and permissions, then click Generate.

   

4. Copy Basic (Base64) for the key. This is the complete base64(key_id:secret) value; use it as-is for INWORLD_API_KEY. Do not encode it again. See API key authentication.

Choose whether each API key has write permission for:

• Voice API: required for POST, PATCH, and DELETE endpoints (clone voice, update voice, delete voice). GET endpoints only require read permissions.
• Router API: required for POST, PATCH, and DELETE endpoints (create router, update router, delete router). GET endpoints only require read permissions.

These permissions do not affect 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

inworld auth print-api-key returns the selected key’s Base64 credential, or the existing INWORLD_API_KEY value if set. It does not mint a client token.

--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 created from a key inherit exactly its permissions.

Realtime-only API keys

A Realtime-only key is built specifically for the Inworld Realtime API. Use it for voice agents that connect over WebSocket or WebRTC. It limits access to Realtime, so other APIs are not exposed if the key leaks.

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 Manage > API Keys, click Generate new key, and choose Realtime-only as the key type. Click Generate, then copy Basic (Base64).

Managing keys

• Deleting a key immediately invalidates it and every token created from it. See Security best practices for what to do if a credential leaks.
• Use separate keys for each environment and integration, so deleting one affects fewer services.
• Usage is attributed per key in the usage dashboard.