From b4c95f2f7bfda4b7b7384d59974ffbb0a8788c67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Veljko=20Popovi=C4=87?= <veljko_popovic_90@hotmail.com>
Date: Tue, 18 Aug 2026 13:28:32 +0200
Subject: [PATCH] DEV-1815: stop apiUrl example from leaking Fliplet auth
 headers to third parties

The "Using Custom API URL" example showed Fliplet.API.request() with
apiUrl pointed at an external service. Fliplet's Auth-token/Authorization
headers are attached unconditionally regardless of apiUrl, so following
that example leaks the user's Fliplet session credentials to whatever
third-party host is set.

Replaces the example with a legitimate Fliplet-owned-host use case, adds
an explicit warning against pointing apiUrl at third parties, and points
readers to fetch() with the third party's own credentials instead.

Follow-up from fliplet-studio PR #8851 (DEV-1802) review, where this doc
example was found to contradict the fix being made to the V3 AI builder
prompt.
---
 docs/API/core/api.md | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/docs/API/core/api.md b/docs/API/core/api.md
index bdb7ab03..0af31508 100644
--- a/docs/API/core/api.md
+++ b/docs/API/core/api.md
@@ -36,7 +36,7 @@ Fliplet.API.request(options)
 | `headers` | Object | `{}` | Additional headers to include with the request. |
 | `cache` | Boolean | `false` | Whether to cache the response for identical requests. |
 | `required` | Boolean | `false` | If true, failed requests will be queued for retry when connection is restored. |
-| `apiUrl` | String | Auto-detected | Custom API URL to use instead of the default. |
+| `apiUrl` | String | Auto-detected | Override the host for another **Fliplet-owned** API (e.g. a regional deployment). Fliplet's `Auth-token`/`Authorization` headers are still attached regardless of this override — never point it at a third-party host (see warning below). |
 | `contentType` | String | Auto-set | Content type header. Automatically set to 'application/json' for object data. |
 | `processData` | Boolean | Auto-set | Whether jQuery should process the data. Set to false for JSON requests. |
 
@@ -128,24 +128,38 @@ Fliplet.API.request({
 });
 ```
 
-#### Using Custom API URL
+#### Using a Custom Fliplet API Host
 
 ```js
+// apiUrl only overrides the host — Fliplet's own Auth-token/Authorization
+// headers are still attached regardless of this value. Use it only for
+// another Fliplet-owned API host (e.g. a regional deployment), never for
+// a third-party service — see the warning below.
 Fliplet.API.request({
-  url: 'v1/external-service/data',
-  apiUrl: 'https://custom-api.example.com/',
+  url: 'v1/apps/123',
+  apiUrl: 'https://api-eu.fliplet.com/',
   method: 'GET'
 }).then(function(response) {
-  console.log('External data:', response);
+  console.log('App data:', response.app);
 });
 ```
 
+> **Warning — do not use for third-party APIs.** `Fliplet.API.request()` always attaches the current user's Fliplet `Auth-token`/`Authorization` headers, even when `apiUrl` points at a different host. Pointing `apiUrl` at a third-party service (Swoogo, OpenWeatherMap, a customer's own REST API, etc.) leaks the user's Fliplet session credentials to that host on every request. For third-party calls, use native `fetch()` with the full absolute endpoint URL and the third party's own credentials instead:
+>
+> ```js
+> const response = await fetch('https://api.example.com/v1/resource', {
+>   method: 'GET',
+>   headers: { Authorization: `Bearer ${thirdPartyApiKey}` }
+> });
+> ```
+
 ### Authentication
 
 All requests are automatically authenticated using:
 - **Auth-token** header with the current user's authentication token
 - **Authorization** header with Bearer token (when btoa is available)
 - Automatic token refresh when the session expires
+- These headers are attached unconditionally, including when `apiUrl` overrides the host — see the warning above
 
 ### Automatic Headers