Skip to content

Commit ea940e6

Browse files
jeffrey-hoekman-vapiclaudestephenvapiai
authored
VAP15-80 docs: document public-key model URL rejection (#1404)
* VAP15-80 docs: document public-key model URL rejection VAPSEC-618 changed a documented contract: a web call or chat (POST /call/web, /chat/web, /chat/web/responses) authenticated with a public API key or a public JWT now gets a 403 if model.url appears anywhere in the request body. The docs still presented transient assistants and assistantOverrides as interchangeable with saved configuration from the browser, so a customer hitting the 403 had no page explaining it. The cohort email needs a stable URL to link to. - transient-vs-permanent-configurations.mdx: a "Model URLs on public-key requests" section covering scope, the request-body locations, who is unaffected, the literal 403 body, and the two fixes (save the assistant and pass assistantId, or start the call server-side with a private key). - using-your-server.mdx: a Note under the Custom LLM URL step pointing to that section. The 403 message is quoted verbatim from CALLER_MODEL_URL_REJECTION_MESSAGE so support can search for it. Scope says "public API key or public JWT", not "public key". The enforced auth paths are api-key-public, customer-jwt-public and customer-jwt-untagged; VAPSEC-618 deliverable 4 settled that both JWT paths stay enforced, since Origin is caller-controlled and the token type is the only boundary an attacker can't forge. org-jwt and workos-jwt (dashboard) callers are not enforced and are excluded. The ramp is deliberately not described. fern check: 0 errors, no warnings on the edited pages. Refs VAP15-80, VAPSEC-618, VAPSEC-906 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * VAP15-80 docs: apply review suggestions and scope fixes - Use "stored assistant" throughout, matching the page and the 403 body - Name the Custom LLM URL field next to model.url - List squad.membersOverrides as its own location - Clarify private keys and private JWTs are unaffected on POST /call and /chat - Add a phased-rollout Note - Note variableValues is the only override on the public chat routes - Add private JWT to the server-side fix; fold the Warning into it - Trim the custom LLM Note per review Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * VAP15-80 docs: drop Vapi as the actor per review Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Steve Smtih <stephen@vapi.ai>
1 parent 87cec58 commit ea940e6

2 files changed

Lines changed: 37 additions & 0 deletions

File tree

‎fern/assistants/concepts/transient-vs-permanent-configurations.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,39 @@ The following examples are `assistant.model` fragments:
260260
cannot be managed through the dashboard or reused across calls.
261261
</Warning>
262262

263+
### Model URLs on public-key requests
264+
265+
A request authenticated with a public API key or a public JWT can't supply a model URL (`model.url`, the **Custom LLM URL** field in the Dashboard). This applies to `POST /call/web`, `POST /chat/web`, and `POST /chat/web/responses`, which are the endpoints the Vapi Web SDK and the chat widget use. A JWT with no `token` claim counts as a public JWT. For more information, see [JWT authentication](/customization/jwt-authentication).
266+
267+
The request is rejected when `model.url` appears anywhere in the request body, including:
268+
269+
- a transient `assistant`
270+
- `assistantOverrides`, including a `tools:append` entry
271+
- a transient `squad` member, its `assistantOverrides`, `squad.membersOverrides`, or `squadOverrides`
272+
- the destinations of a handoff tool, at any depth
273+
- a transient `workflow` or one of its nodes
274+
275+
A model URL on a stored assistant isn't affected. Neither are Dashboard sessions, or requests to `POST /call` or `POST /chat` authenticated with a private API key or a private JWT.
276+
277+
<Note>
278+
Vapi is turning on this check for organizations in phases, and emails affected organizations before the check applies to them.
279+
</Note>
280+
281+
A rejected request returns a `403` response with this body:
282+
283+
```json
284+
{
285+
"message": "Supplying `model.url` in the request body is not permitted on public-key authenticated calls. Configure the model URL on a stored assistant instead.",
286+
"error": "Forbidden",
287+
"statusCode": 403
288+
}
289+
```
290+
291+
To avoid the rejection, use one of these approaches:
292+
293+
- **Store the assistant.** Set `model.url` on a stored assistant, then pass its `assistantId` from the browser. Keep per-call changes in `assistantOverrides` fields that don't set a model URL, such as `variableValues`. On `POST /chat/web` and `POST /chat/web/responses`, `variableValues` is the only `assistantOverrides` field accepted.
294+
- **Start the call or chat from your server.** Send the request to `POST /call` or `POST /chat` with your private API key or a private JWT, which can still supply a model URL. Never send your private API key to a browser or mobile app.
295+
263296
## Permanent configurations
264297

265298
Use **permanent configurations** for reusable setups that multiple teams can access and manage through the dashboard.

‎fern/customization/custom-llm/using-your-server.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,10 @@ On the **Assistant** tab, select **MODEL**. In **Model Settings**, open **Model*
6161
**3. Enter Ngrok URL:**
6262
Enter `gpt-4.1-mini` in the second **Model** field. Paste the public base URL for your OpenAI-compatible endpoint into **Custom LLM URL** (for example, the URL generated by Ngrok for your server). The server handles requests at `/chat/completions`.
6363

64+
<Note>
65+
Set the custom LLM URL on a stored assistant, as in this step. A web call or chat authenticated with a public API key or a public JWT that supplies `model.url` is rejected with a `403` response. For more information, including how to set the URL per request from your server, see [Model URLs on public-key requests](/assistants/concepts/transient-vs-permanent-configurations#model-urls-on-public-key-requests).
66+
</Note>
67+
6468
**4. Test the Connection:**
6569
Select **Publish**, review the changes, then select **Next**. Review the version and traffic settings, then select **Publish**. Select **Talk** to test the assistant in the Dashboard. Check that your server receives the request and the assistant responds.
6670

0 commit comments

Comments
 (0)