From 10aa369dae3948a0e1de51fae837c865b77d5be6 Mon Sep 17 00:00:00 2001
From: Mike Purvis <mikedotexe@gmail.com>
Date: Wed, 24 Jun 2026 12:21:51 -0700
Subject: [PATCH] docs(browser-keys): note sandboxed-iframe (Origin: null)
 limitation

A sandboxed <iframe> sends Origin: null and usually omits Referer, so a
website-restricted key 403s even on the operator's own domain. Add a
failure-mode entry (EN + ru) so operators don't expect an embedded widget to
work with a restricted browser key. Addresses the PR #20 review design note.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/auth/browser-keys.mdx                                  | 6 ++++++
 .../current/auth/browser-keys.mdx                           | 4 ++++
 2 files changed, 10 insertions(+)

diff --git a/docs/auth/browser-keys.mdx b/docs/auth/browser-keys.mdx
index 3373d29..8b57314 100644
--- a/docs/auth/browser-keys.mdx
+++ b/docs/auth/browser-keys.mdx
@@ -190,6 +190,12 @@ restricted browser key, served from a domain you listed on the key.
 Use two keys: a restricted browser key for the frontend, and an unrestricted server key for the backend.
 Do not try to share one key across both.
 
+### My key fails from inside an embedded or sandboxed iframe
+
+A sandboxed `<iframe>` sends `Origin: null` and usually omits `Referer`, so a website-restricted key
+returns `403 origin_not_allowed` even on your own domain. A widget in a sandboxed iframe can't use a
+restricted browser key — call FastNear from the top-level page, or route through a server-side path.
+
 ## Related guides
 
 - [Auth & Access](/auth) — the server-key default and transport choices
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/auth/browser-keys.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/auth/browser-keys.mdx
index ff26a2b..a87b519 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/auth/browser-keys.mdx
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/auth/browser-keys.mdx
@@ -163,6 +163,10 @@ const res = await fetch(`https://rpc.mainnet.fastnear.com?apiKey=${FASTNEAR_API_
 
 Используйте два ключа: браузерный ключ с ограничением для фронтенда и серверный ключ без ограничений для бэкенда. Не пытайтесь использовать один ключ для обоих случаев.
 
+### Ключ не работает из встроенного или изолированного iframe
+
+Изолированный `<iframe>` отправляет `Origin: null` и обычно не передаёт `Referer`, поэтому ключ с ограничением по сайтам возвращает `403 origin_not_allowed` даже на собственном домене. Виджет в изолированном iframe не может использовать браузерный ключ с ограничением — вызывайте FastNear со страницы верхнего уровня или используйте серверный путь.
+
 ## Связанные руководства
 
 - [Аутентификация и доступ](/auth) — серверный ключ по умолчанию и выбор способа передачи