You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 019d656
Browse filesBrowse the repository at this point in the historyBrowse 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>
Copy file name to clipboardExpand all lines: fern/server-url/server-authentication.mdx
+24-12Lines changed: 24 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -407,21 +407,27 @@ For webhooks sent to a server URL supplied in the API request, Vapi also strips
407
407
408
408
#### Subsystem server URLs
409
409
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:
411
411
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
420
419
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.
422
428
423
429
<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.
425
431
</Warning>
426
432
427
433
#### 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:
432
438
Assistant credentials withheld from <messageType>: this server url came from an assistant this request supplied, not from your org configuration
433
439
```
434
440
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**.
436
448
437
449
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`.
Copy file name to clipboardExpand all lines: fern/squads/handoff/destinations.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -150,7 +150,7 @@ Best for Anthropic models -- single tool with multiple destination options:
150
150
The destination is determined at runtime via the `handoff-destination-request` webhook:
151
151
152
152
<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).
154
154
</Warning>
155
155
156
156
```json
@@ -164,7 +164,7 @@ A destination's `server` block follows the assistant carrying it. On a saved ass
0 commit comments