diff --git a/src/pages/agent-network/providers.mdx b/src/pages/agent-network/providers.mdx
index e8c3a685..58b54886 100644
--- a/src/pages/agent-network/providers.mdx
+++ b/src/pages/agent-network/providers.mdx
@@ -59,12 +59,61 @@ and budgets (see [How It Works](/agent-network/how-it-works#llm-apis-and-ai-gate
the vendor's own list — see [Load Models from the Provider](#load-models-from-the-provider).
5. _(Optional, gateways)_ Fill any gateway-specific fields (for example a Portkey config
ID) and the identity headers used for attribution.
-6. Save the provider.
+6. Save the provider. NetBird checks the upstream URL and the credential against the
+ vendor before storing them — see [The Save-Time Check](#the-save-time-check).
+### The Save-Time Check
+
+Before storing a provider, NetBird asks the vendor whether the upstream URL and the
+credential work, using the same model listing that
+[Load models from provider](#load-models-from-the-provider) uses. A record that cannot reach
+its vendor is refused at the form, rather than saving cleanly and surfacing later as a
+refused request or an empty model list with nothing tying it back to the record.
+
+If the vendor refuses, the provider is not saved. The form stays open with what you typed
+still in it, and the message names which of the two is at fault: the credential was
+rejected, or the upstream URL could not be reached or does not answer a model listing. Fix
+the field it names and save again.
+
+On an existing provider, the check runs only when you change the **Upstream URL**, the
+**API key**, or the **Provider** the record is connected to — renaming a provider, editing
+model rows or changing prices saves without asking the vendor anything. Three consequences
+worth knowing:
+
+- **Changing only the URL tests it against the stored credential.** The key never returns to
+ your browser, so there is nothing else it could be tested with.
+- **A rejected key never replaces a working one.** If you paste a new key and the vendor
+ refuses it, the provider keeps running on the old one.
+- **Switching the provider re-checks the credential you already stored.** It was accepted by
+ one vendor; the record now points at another, which has never seen it.
+
+**Which providers are checked.** The same four that can list their models: **OpenAI**,
+**Anthropic**, **Amazon Bedrock** and **Google Vertex AI**. Everything else saves without a
+check, because there is no listing to ask for or no way to reach it:
+
+- Azure OpenAI, Mistral, Kimi, the AI gateways and custom endpoints, which publish no
+ listing NetBird can ask for.
+- A Bedrock provider pointed at a proxy or a self-hosted endpoint rather than an AWS runtime
+ host, because the control plane that serves the listing is derived from that URL and
+ cannot be worked out from an address AWS does not own. The credential goes unverified, but
+ the URL does not: Bedrock lists from a different host than it serves requests on, so the
+ one you entered is resolved on its own, and one that does not exist is refused.
+- Any upstream on a private address. Your agents reach it through the tunnel, but NetBird's
+ management service has no route to it, so there is nothing it can ask.
+
+An unchecked provider is not a lesser one; NetBird simply has no way to verify it up front,
+so it saves what you entered.
+
+
+A vendor outage also fails the save — the check cannot confirm the provider either way, and
+saving something unverified is what it exists to prevent. If the message says the provider
+returned an error rather than naming your URL or credential, wait and save again.
+
+
## Custom & Self-hosted Providers
Pick **Custom / Self-hosted** for any OpenAI-compatible endpoint that isn't a first-party
@@ -167,7 +216,8 @@ A few details worth knowing:
still count toward the token caps.
- **Editing a saved provider reuses the stored credential.** The API key (or, on Vertex AI,
the uploaded service account key) never returns to your browser, so the lookup runs against
- the credential already on the record. Change the provider, the upstream URL, or the masked
+ the credential already on the record. A retyped **Upstream URL** is sent with it, so a new
+ endpoint can be listed before it is saved. Change the provider or type over the masked
credential and NetBird asks for a credential to use instead — the values on screen are
then used.
- **Bedrock ids are registered exactly as AWS issues them**, prefix included