Integration keys

Voice connections reach your agents through a WebSocket URL that anyone who learns it could call. Integration keys make VirtuAI accept those connections only when they carry a key from your workspace.

Manage them under Manage > Integrations. This requires settings.manage.

What enforcement covers

With Key Enforcement on, this connection must carry a valid key:

Endpoint	How to send the key
Voice WebSocket	X-API-Key header, or the api_key query parameter

The web voice widget doesn’t send a key, so it can’t connect while enforcement is on.

Every other way in is verified with the platform’s own mechanism, and doesn’t use integration keys whether enforcement is on or off:

Channel	How VirtuAI verifies it
WhatsApp	The X-Twilio-Signature that Twilio computes with your Twilio auth token
Google Chat	Google’s token, checked against your Google Cloud project number (GOOGLE_CHAT_PROJECT_NUMBER)
Slack	The Slack app’s signing secret
Telegram	The secret VirtuAI generates when you register the webhook
Web chat	A signed-in member of the workspace
A2A	The client’s own credentials, created on the A2A clients card in Settings

Note

Google Chat is verified with Google’s token only once GOOGLE_CHAT_PROJECT_NUMBER is set. Set it as part of the Google Chat setup: in a workspace with enforcement on and no project number, Google Chat messages are rejected, because Google Chat can’t send a key.

When you edit an agent, its Integration URLs card marks the Voice WebSocket with Requires X-API-Key while enforcement is on. It is the only URL that needs a key; the other channels are verified as shown above.

Turn it on

1. Open Integrations. Under Create New Key, enter a name that says where the key is used, for example Voice Prod, and select Create.
2. Copy the key from Copy Your API Key. It’s shown only once: VirtuAI stores a hash, not the key.
3. Configure the voice connection to send the key.
4. Turn on Key Enforcement.

New workspaces start with enforcement on. The toggle sets the INTEGRATION_KEYS_ENFORCED workspace setting.

Caution

Before you turn enforcement on, confirm that your voice connections send the key. Once it’s on, a voice connection without a valid key is refused, and the web voice widget can’t connect.

When a connection is rejected

A voice connection without a valid key is refused before it opens. One of these is the cause:

• No key was sent.
• The value isn’t a VirtuAI integration key.
• The key doesn’t belong to this agent’s workspace, or it was revoked.

If Google Chat requests are rejected with 401 · X-API-Key header is required, the workspace has enforcement on and no Google Cloud project number. Set GOOGLE_CHAT_PROJECT_NUMBER as described in Google Chat.

Managing keys

The API Keys list shows every key with its name, its status (Active or Revoked), its Prefix and when it was Last used. The prefix, such as via_1a2b3c4d, is the start of the key, so you can tell which key a connection uses without seeing the secret. Last used is updated at most every five minutes.

• A workspace can have up to 5 active keys. Names must be unique among active keys.
• A key only works for the workspace that created it.
• Revoke takes effect immediately and can’t be undone.

Rotating a key

There’s no rotate button, so rotate by overlapping two keys:

1. Create a new key.
2. Update the voice connection to send the new key, and check that it still connects.
3. Revoke the old key.

Revoke a key as soon as you suspect it has leaked, and whenever someone who had it leaves.