API Key Substitutions

Why Use Placeholders?

Configuring a VNS AI session requires API keys — an OpenAI key, bearer tokens for your webhook endpoints, and similar secrets. The straightforward approach is to paste those keys directly into the JSON configuration, but that creates real security risks:

• ✗ Keys in JSON files end up in source control, logs, or configuration exports where they can be seen by anyone with access.
• ✗ Rotating a key means finding and updating every place it appears — easy to miss one.
• ✗ Sharing a configuration snippet with a developer or support team exposes the live key.

VNS placeholders solve this. Instead of embedding a secret, you store it once in the VNS Portal under a name you choose, then reference that name in your JSON with a placeholder tag. At call time, VNS substitutes the real value — the key itself never appears in your configuration files.

Placeholder Syntax

A placeholder is a tag with three parts:

<<vns-api-token:ProfileName>>

Where Placeholders Can Be Used

Placeholders are resolved anywhere inside the VoiceElements_Instructions JSON — header values, URLs, or any other string field. The most common locations are:

1. AI provider WebSocket headers

Secure your OpenAI (or other AI provider) authorization header:

"aiUrl": {
  "url": "wss://api.openai.com/v1/realtime?model=gpt-realtime",
  "headers": {
    "Authorization": "Bearer <<vns-api-token:MyOpenAiKey>>"
  }
}

2. Toolkit (webhook endpoint) headers

Secure the token sent to your tool endpoint on every tool call:

"toolkits": [
  {
    "name": "default",
    "url": "https://your-api.example.com/api/tool",
    "headers": {
      "Token": "<<vns-api-token:MyWebhookApiKey>>"
    },
    "toolsUrlAdapter": "?toolName=<<toolname>>&sessionGuid=<<sessionguid>>"
  }
]

3. Anywhere else in the session JSON

Placeholders work in any string field inside VoiceElements_Instructions — instructions text, URL strings, or any other value.

Storing Keys in the VNS Portal

Keys are stored in the VNS Portal. Each key is stored under a name you choose — that name is what goes in the ProfileName part of the placeholder.

Resolution Timing

Placeholders are resolved at the start of each call, just before the configuration is sent to the AI provider. The stored key value is substituted in place of the placeholder tag. The raw placeholder is never sent to OpenAI or to your webhook endpoint.

Full Example

A customer stored their OpenAI key under the name OpenAiProd and their webhook token under MyIvrApiKey in the portal. Their VoiceElements_Instructions looks like this:

{
  "VoiceElements_Instructions": {
    "aiUrl": {
      "url": "wss://api.openai.com/v1/realtime?model=gpt-realtime",
      "headers": {
        "Authorization": "Bearer <<vns-api-token:OpenAiProd>>"
      }
    },
    "toolkits": [
      {
        "name": "default",
        "url": "https://mycompany.example.com/api/ivr",
        "headers": {
          "X-Api-Key": "<<vns-api-token:MyIvrApiKey>>"
        },
        "toolsUrlAdapter": "?toolName=<<toolname>>&sessionGuid=<<sessionguid>>"
      }
    ]
  }
}

At call time, VNS looks up OpenAiProd and MyIvrApiKey from the customer's stored credentials and substitutes the real values before any network calls are made. Neither placeholder ever appears in outbound requests.