Skip to content

Commit 019d656

Browse files
VAP15-54 docs: align subsystem credentials with the VAPSEC-627 stack
Withholding is decided per assistant: one caller-supplied server in assistantOverrides withholds the org credential from every subsystem request on that assistant, saved tools included. Add apiRequest and MCP requests, list what is withheld, document the second log entry, and rename the handoff example token placeholder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 5603acc commit 019d656

2 files changed

Lines changed: 27 additions & 15 deletions

File tree

‎fern/server-url/server-authentication.mdx‎

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -407,21 +407,27 @@ For webhooks sent to a server URL supplied in the API request, Vapi also strips
407407

408408
#### Subsystem server URLs
409409

410-
Some webhooks go to a URL owned by a subsystem rather than to your assistant's webhook URL. Tools, knowledge bases, custom voices, dynamic handoff and transfer destinations, and custom endpointing providers each carry their own `server` block:
410+
Tools, knowledge bases, custom voices, handoff and transfer destinations, and custom endpointing providers each carry their own `server` block. These requests go to that block's URL, not to your assistant's webhook URL:
411411

412-
| Webhook | Server it is sent to |
413-
| --- | --- |
414-
| `tool-calls`, `function-call` | the tool's |
415-
| `knowledge-base-request` | the knowledge base's |
416-
| `voice-request` | the custom voice's |
417-
| `handoff-destination-request` | the handoff destination's |
418-
| `transfer-destination-request` | the transfer destination's |
419-
| `call.endpointing.request` | the endpointing provider's |
412+
- `tool-calls` and `function-call`, to the tool's server
413+
- `knowledge-base-request`, to the knowledge base's server
414+
- `voice-request`, to the custom voice's server
415+
- `handoff-destination-request` and `transfer-destination-request`, to the destination's server
416+
- `call.endpointing.request`, to the endpointing provider's server
417+
- `apiRequest` tool requests, to the tool's URL
418+
- MCP requests, to the MCP server's URL, both when Vapi lists its tools at call start and on each tool call
420419

421-
**These follow the assistant that carried them.** A tool on a saved assistant is org-configured and keeps your credentials. The same tool on a transient assistant or in `assistantOverrides` is caller-authored, and Vapi sends to its URL without them.
420+
When a transient assistant or `assistantOverrides` supplies a server URL or `credentialId` for any of these, Vapi withholds your org credential from **every** request in this list whose URL differs from your assistant's webhook URL. On a withheld request:
421+
422+
- your org's `secret`, `headers`, and credential are not sent
423+
- a `credentialId` in the request is ignored, because it points at a credential stored in your org
424+
- the `secret` and `headers` you set in that `server` block are still sent
425+
- credential fields in the payload arrive as `"[REDACTED]"`
426+
427+
Overrides that set only `variableValues` don't trigger this. In chats, the setting lasts for the whole session, including resumed sessions and handoffs.
422428

423429
<Warning>
424-
A saved assistant can carry a caller-authored subsystem server: if `assistantOverrides` replaces the voice, the tools, or the knowledge base, those replacements are caller-authored even though the assistant itself is saved. Give any subsystem server you supply in a request its own authentication in that block's `headers`.
430+
Supplying one tool, voice, or knowledge base through `assistantOverrides` also withholds your org credential from the saved assistant's own tools, voice, and knowledge base. Put authentication for those endpoints in their `server.headers`, or move the override onto a saved assistant.
425431
</Warning>
426432

427433
#### Confirming a withheld send in your logs
@@ -432,7 +438,13 @@ When Vapi withholds credentials, it also writes an entry to the call's logs:
432438
Assistant credentials withheld from <messageType>: this server url came from an assistant this request supplied, not from your org configuration
433439
```
434440

435-
Open the call in [**Calls**](/observability/logs/call-logs) under **Logs**. On its **Logs** tab, search for `credentials withheld`. Leave the category filter unset: the entry is not always filed under **Webhook**.
441+
For a tool, custom voice, or MCP request withheld under [Subsystem server URLs](#subsystem-server-urls), the entry reads:
442+
443+
```text
444+
Assistant credentials withheld from <destination>: this assistant carries server configuration this request supplied
445+
```
446+
447+
Open the call in [**Calls**](/observability/logs/call-logs) under **Logs**. On its **Logs** tab, search for `credentials withheld`, which matches both entries. Leave the category filter unset: the entry is not always filed under **Webhook**.
436448

437449
Vapi writes the entry **on each send** of a message type that is not suppressed. The same entry can repeat within a call. Vapi suppresses it for high-volume message types: `model-output`, `speech-update`, `status-update`, `transcript`, `transcript[transcriptType="final"]`, `voice-input`, and `voice-request`.
438450

‎fern/squads/handoff/destinations.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ Best for Anthropic models -- single tool with multiple destination options:
150150
The destination is determined at runtime via the `handoff-destination-request` webhook:
151151

152152
<Warning>
153-
A destination's `server` block follows the assistant carrying it. On a saved assistant it keeps your org's webhook credentials; supplied through a transient assistant or `assistantOverrides` it is caller-authored, and Vapi sends to it without them. Give it its own authentication in `server.headers`, as the examples below do. See [Server authentication](/server-url/server-authentication#subsystem-server-urls).
153+
If a transient assistant or `assistantOverrides` supplies any tool, voice, or destination server, Vapi sends `handoff-destination-request` without your org credential. Put authentication in `server.headers`, as these examples do; see [Subsystem server URLs](/server-url/server-authentication#subsystem-server-urls).
154154
</Warning>
155155

156156
```json
@@ -164,7 +164,7 @@ A destination's `server` block follows the assistant carrying it. On a saved ass
164164
"server": {
165165
"url": "https://api.example.com/determine-handoff-destination",
166166
"headers": {
167-
"Authorization": "Bearer YOUR_API_KEY"
167+
"Authorization": "Bearer YOUR_WEBHOOK_TOKEN"
168168
}
169169
}
170170
}
@@ -225,7 +225,7 @@ Pass additional context to your webhook for intelligent routing:
225225
"server": {
226226
"url": "https://api.example.com/intelligent-routing",
227227
"headers": {
228-
"Authorization": "Bearer YOUR_API_KEY"
228+
"Authorization": "Bearer YOUR_WEBHOOK_TOKEN"
229229
}
230230
}
231231
}

0 commit comments

Comments
 (0)