From ccfd9094500eea80a88649c3446d6e8f70ba4047 Mon Sep 17 00:00:00 2001 From: Jeff Hoekman Date: Sat, 7 Nov 2026 10:12:02 -0500 Subject: [PATCH 1/3] 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 --- .../transient-vs-permanent-configurations.mdx | 33 +++++++++++++++++++ .../custom-llm/using-your-server.mdx | 4 +++ 2 files changed, 37 insertions(+) diff --git a/fern/assistants/concepts/transient-vs-permanent-configurations.mdx b/fern/assistants/concepts/transient-vs-permanent-configurations.mdx index e69ff4b7c..bb09a2541 100644 --- a/fern/assistants/concepts/transient-vs-permanent-configurations.mdx +++ b/fern/assistants/concepts/transient-vs-permanent-configurations.mdx @@ -260,6 +260,39 @@ The following examples are `assistant.model` fragments: cannot be managed through the dashboard or reused across calls. +### Model URLs on public-key requests + +A request authenticated with a public API key or a public JWT can't supply a model URL. 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). + +Vapi rejects the request when `model.url` appears anywhere in the request body, including: + +- a transient `assistant` +- `assistantOverrides`, including a `tools:append` entry +- a transient `squad` member, its overrides, or `squadOverrides` +- the destinations of a handoff tool, at any depth +- a transient `workflow` or one of its nodes + +A model URL stored on a saved assistant isn't affected. Neither are requests authenticated with a private API key, a private JWT, or a dashboard session. + +A rejected request returns a `403` response with this body: + +```json +{ + "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.", + "error": "Forbidden", + "statusCode": 403 +} +``` + +To fix it, use one of these approaches: + +- **Save the assistant.** Set `model.url` on a saved 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`. +- **Start the call or chat from your server.** Send the request to `POST /call` or `POST /chat` with your private API key. A private API key can still supply a model URL. + + +Never send your private API key to a browser. If the model URL has to change per call, choose it on your server. + + ## Permanent configurations Use **permanent configurations** for reusable setups that multiple teams can access and manage through the dashboard. diff --git a/fern/customization/custom-llm/using-your-server.mdx b/fern/customization/custom-llm/using-your-server.mdx index 047460dca..968de36d8 100644 --- a/fern/customization/custom-llm/using-your-server.mdx +++ b/fern/customization/custom-llm/using-your-server.mdx @@ -61,6 +61,10 @@ On the **Assistant** tab, select **MODEL**. In **Model Settings**, open **Model* **3. Enter Ngrok URL:** 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`. + +Set the custom LLM URL on a saved assistant, as in this step. A web call or chat authenticated with a public API key or a public JWT can't supply `model.url` in the request, and Vapi rejects it with a `403` response. To set the URL per request, start the call from your server with your private API key. For more information, see [Model URLs on public-key requests](/assistants/concepts/transient-vs-permanent-configurations#model-urls-on-public-key-requests). + + **4. Test the Connection:** 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. From b7bc90ae340163d9faf422b7fd0a43c30d1828cc Mon Sep 17 00:00:00 2001 From: Jeff Hoekman Date: Mon, 9 Nov 2026 13:03:40 -0500 Subject: [PATCH 2/3] 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 --- .../transient-vs-permanent-configurations.mdx | 20 +++++++++---------- .../custom-llm/using-your-server.mdx | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/fern/assistants/concepts/transient-vs-permanent-configurations.mdx b/fern/assistants/concepts/transient-vs-permanent-configurations.mdx index fe8e5f1e4..6a1c6f793 100644 --- a/fern/assistants/concepts/transient-vs-permanent-configurations.mdx +++ b/fern/assistants/concepts/transient-vs-permanent-configurations.mdx @@ -262,17 +262,21 @@ The following examples are `assistant.model` fragments: ### Model URLs on public-key requests -A request authenticated with a public API key or a public JWT can't supply a model URL. 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). +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). Vapi rejects the request when `model.url` appears anywhere in the request body, including: - a transient `assistant` - `assistantOverrides`, including a `tools:append` entry -- a transient `squad` member, its overrides, or `squadOverrides` +- a transient `squad` member, its `assistantOverrides`, `squad.membersOverrides`, or `squadOverrides` - the destinations of a handoff tool, at any depth - a transient `workflow` or one of its nodes -A model URL stored on a saved assistant isn't affected. Neither are requests authenticated with a private API key, a private JWT, or a dashboard session. +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. + + +Vapi is turning on this check for organizations in phases, and emails affected organizations before the check applies to them. + A rejected request returns a `403` response with this body: @@ -284,14 +288,10 @@ A rejected request returns a `403` response with this body: } ``` -To fix it, use one of these approaches: - -- **Save the assistant.** Set `model.url` on a saved 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`. -- **Start the call or chat from your server.** Send the request to `POST /call` or `POST /chat` with your private API key. A private API key can still supply a model URL. +To avoid the rejection, use one of these approaches: - -Never send your private API key to a browser. If the model URL has to change per call, choose it on your server. - +- **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. +- **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. ## Permanent configurations diff --git a/fern/customization/custom-llm/using-your-server.mdx b/fern/customization/custom-llm/using-your-server.mdx index 968de36d8..8c6e5f7ec 100644 --- a/fern/customization/custom-llm/using-your-server.mdx +++ b/fern/customization/custom-llm/using-your-server.mdx @@ -62,7 +62,7 @@ On the **Assistant** tab, select **MODEL**. In **Model Settings**, open **Model* 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`. -Set the custom LLM URL on a saved assistant, as in this step. A web call or chat authenticated with a public API key or a public JWT can't supply `model.url` in the request, and Vapi rejects it with a `403` response. To set the URL per request, start the call from your server with your private API key. For more information, see [Model URLs on public-key requests](/assistants/concepts/transient-vs-permanent-configurations#model-urls-on-public-key-requests). +Set the custom LLM URL on a stored assistant, as in this step. Vapi rejects a web call or chat authenticated with a public API key or a public JWT that supplies `model.url`, 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). **4. Test the Connection:** From 6b08e64c01ed47f31e075e638665d792217f1159 Mon Sep 17 00:00:00 2001 From: Jeff Hoekman Date: Mon, 9 Nov 2026 14:34:51 -0500 Subject: [PATCH 3/3] VAP15-80 docs: drop Vapi as the actor per review Co-Authored-By: Claude Opus 5.5 --- .../concepts/transient-vs-permanent-configurations.mdx | 2 +- fern/customization/custom-llm/using-your-server.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/assistants/concepts/transient-vs-permanent-configurations.mdx b/fern/assistants/concepts/transient-vs-permanent-configurations.mdx index 6a1c6f793..cb90056e0 100644 --- a/fern/assistants/concepts/transient-vs-permanent-configurations.mdx +++ b/fern/assistants/concepts/transient-vs-permanent-configurations.mdx @@ -264,7 +264,7 @@ The following examples are `assistant.model` fragments: 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). -Vapi rejects the request when `model.url` appears anywhere in the request body, including: +The request is rejected when `model.url` appears anywhere in the request body, including: - a transient `assistant` - `assistantOverrides`, including a `tools:append` entry diff --git a/fern/customization/custom-llm/using-your-server.mdx b/fern/customization/custom-llm/using-your-server.mdx index 8c6e5f7ec..042921548 100644 --- a/fern/customization/custom-llm/using-your-server.mdx +++ b/fern/customization/custom-llm/using-your-server.mdx @@ -62,7 +62,7 @@ On the **Assistant** tab, select **MODEL**. In **Model Settings**, open **Model* 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`. -Set the custom LLM URL on a stored assistant, as in this step. Vapi rejects a web call or chat authenticated with a public API key or a public JWT that supplies `model.url`, 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). +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). **4. Test the Connection:**