skills/vapi-prompt-builder/references/vapi-security-trust.md

# Vapi Security and Trust Boundaries

Use this reference when a Vapi prompt, tool, Squad, or configuration involves authentication, caller identity, account lookup, permissions, secrets, verified values, static parameters, `function.parameters`, dynamic variables, `variableExtractionPlan`, aliases, handoff arguments, or sensitive tool responses.

## Core Rule

Do not use the system prompt, caller speech, LLM-filled arguments, or conversation-derived variables as a security boundary. The prompt can guide behavior, but it cannot make a value trusted or prevent a malicious caller from trying to redirect the model.

Use deterministic Vapi configuration and backend checks for any value the LLM must not be able to fake, override, or leak.

## Trust Tiers

Classify every important value before deciding where it belongs.

### Tier 1: Server-Trusted

Use for values populated from signaling, validated call-start configuration, backend records, or server time. These may be safe for Vapi static/top-level `parameters` when the backend trusts their source.

Examples:

- `{{ customer.number }}` from inbound signaling or validated outbound payload
- `{{ phoneNumber.number }}`
- `{{ transport.callSid }}`
- `{{ call.id }}`
- `{{ assistant.id }}`
- Server-known account IDs or verification status injected at call start through `assistantOverrides.variableValues`
- Server time values such as `{{ now }}` and `{{ currentDateTime }}`

Use these in top-level tool `parameters` when the tool server must receive the trusted value without LLM mediation.

### Tier 2: Conversation-Derived

Do not use as a security boundary. These contain caller speech or conversation text.

Examples:

- `{{ messages }}`
- `{{ transcript }}`
- User-spoken names, phone numbers, emails, account numbers, dates of birth, or intents
- Any variable copied from caller speech into backend memory during the call

Treat these as claims to verify, not facts.

### Tier 3: LLM-Derived

Never use as a security boundary. These are generated or extracted by the model.

Examples:

- Values in `function.parameters`
- Handoff arguments filled by the model
- Handoff-tool-extracted variables from `variableExtractionPlan.schema`
- Aliases extracted from tool responses that were themselves shaped by user-spoken input
- Summaries, classifications, sentiment, urgency, or intent labels generated by the model

These are useful for routing, summarization, and workflow convenience, but not for authentication or authorization.

## Where Trusted Values Belong

For API request and modern function tools, trusted values should usually go in the tool's top-level `parameters` array, not inside `function.parameters`.

Top-level `parameters` are configured by the builder, resolved server-side, hidden from the LLM, and merged into the tool request after LLM-generated arguments. This makes them appropriate for values such as verified caller ID, called number, call ID, account ID, tenant ID, or a backend verification flag.

`function.parameters` is the LLM-facing JSON schema. Put only values the caller may say or the model may infer, such as name, intent, preferred appointment date, or item choice.

## Common Failure Modes To Flag

Flag these as configuration risks:

- Putting trusted values in `function.parameters`, where the model can generate or override them.
- Putting trusted values in body schema defaults instead of top-level static `parameters`.
- Telling the model a trusted value in the system prompt and asking it to forward that value to a tool.
- Treating a caller-spoken value as verified because it was stored in a variable.
- Treating `variableExtractionPlan` aliases as security boundaries when the source response is not server-trusted.
- Passing sensitive secrets, tokens, auth results, or hidden internal fields in tool responses that become visible in conversation history.
- Using handoff arguments or LLM-extracted variables for authentication, permissions, account ownership, or compliance gating.

## Aliases and Extraction Are Not Redaction

Variable extraction aliases can make tool chaining deterministic, but they do not hide the original tool response from the model. If a value must be hidden from the model, the tool server must not include it in the response body.

Use aliases for deterministic forwarding of non-secret fields or server-trusted values from a trusted tool response. Do not use aliases to sanitize, redact, or launder untrusted conversation-derived values into trusted values.

## Handoffs

Handoff arguments and `variableExtractionPlan.schema` values are LLM-derived. Use them for routing context, summaries, intent, sentiment, urgency, or non-sensitive workflow state. Do not use them to prove identity, authorize access, or decide whether the caller is allowed to receive sensitive information.

When trusted data must move across assistants, prefer server-trusted call-start variables, backend-owned state keyed by a trusted call/account identifier, or a trusted tool lookup in the destination assistant.

## Prompt and Tool Response Rules

Keep prompts and examples free of:

- Secrets, API keys, bearer tokens, HMAC secrets, database IDs that should not be exposed, or internal credentials
- Hidden policy details that callers should not hear
- Sensitive tool result fields the model does not need
- Long negative banlists that repeat forbidden content
- Sensitive literal examples that could be copied into output

Use short positive constraints and shape examples instead.

## Output Guidance

When a prompt or configuration has trust-boundary issues, separate the fix from the final prompt:

```text
Configuration needed: move verified caller ID out of `function.parameters` and into top-level static `parameters`, then verify account ownership server-side before returning account details.
```

Do not present an artifact as production-ready when trusted values are still routed through the prompt, caller speech, `function.parameters`, handoff arguments, or untrusted extraction.