安全的地圖 API 驗證設計會按執行環境分離憑證。瀏覽器需要可以公開、但嚴格限制在核准來源和能力範圍內的憑證；後端需要永不進入使用者端程式碼、可授權伺服器間操作的秘密憑證。二者不能互換。應限制範圍、分離環境、監控用量、輪替憑證，並區分身分驗證失敗與授權失敗。Kaleidr 透過公開瀏覽器金鑰 (kld_pk_live_…) 和伺服器金鑰 (kld_sk_live_…) 實作這一模式。
下文介紹瀏覽器與伺服器憑證、來源、CORS、範圍、生命週期、多租戶信任界線和常見錯誤。相關資訊請參閱開發人員文件。SDK 架構請參閱什麼是 AI 地圖 SDK？，嵌入和聊天掛載請參閱如何嵌入互動式地圖以及在 Mapbox、Google Maps 和 MapLibre 上新增 AI 聊天。
身分驗證要點
- 先考量執行環境： 瀏覽器憑證為可公開而設計，伺服器憑證為保密而設計。
- 來源 ≠ 身分驗證： CORS 和允許來源不能替代憑證檢查。
- 範圍 ≠ 租戶： API 能力範圍不等於應用使用者或資料列授權。
- 安全輪替： 撤銷有效金鑰前先部署替代金鑰。
- 記錄檔遮蔽： 記錄金鑰 ID 和狀態碼，絕不記錄憑證值。
為什麼瀏覽器中的地圖 API 驗證不同？
瀏覽器是不受信任的執行環境。傳送給瀏覽器的內容通常都能透過頁面原始碼、開發人員工具、網路請求、打包後的 JavaScript、瀏覽器儲存空間或執行階段物件檢查。在使用者端程式碼中放置長期伺服器機密資訊——包括 React 原始碼、Next.js NEXT_PUBLIC_*、Vite VITE_*、HTML、行動 WebView 或前端 JSON——並不安全，因為瀏覽器無法向執行它的人隱藏機密資訊。應詢問憑證允許做什麼、允許在哪裡執行，而不是如何把金鑰藏進前端套件。
| 屬性 | 公開／瀏覽器憑證 | 伺服器憑證 |
|---|---|---|
| 預期環境 | 瀏覽器或使用者端 SDK | 受信任後端 |
| 在使用者端可見 | 可能 | 絕不 |
| 安全模型 | 受限能力 + 核准來源 + 短期工作階段（如支援） | 秘密 bearer 憑證 |
| 主要風險 | 未授權重複使用或配額濫用 | 帳號或資料外洩 |
不同平台名稱不同，但模式相同。Kaleidr 使用公開金鑰和伺服器金鑰（Auth & Scopes）。Mapbox 區分公開與秘密權杖範圍，並要求秘密權杖請求從伺服器發出（安全使用 Mapbox）。Google Maps Platform 使用應用和 API 限制，並建議保護 Web 服務憑證；伺服器間造訪在支援時使用 OAuth 2.0（安全性指南）。使用者端憑證應為公開而設計，伺服器憑證應為保密而設計。
Kaleidr 公開金鑰和伺服器金鑰如何工作？
目前文件為同一組織和能力系統定義兩種金鑰。公開金鑰以 kld_pk_live_… 開頭，用於 HTML、Kaleidr SDK、<kaleidr-map> 和瀏覽器整合。SDK 在執行階段將其換成與來源綁定的短期工作階段，而不是把字串作為長期 bearer 憑證。伺服器金鑰以 kld_sk_live_… 開頭，僅用於受信任伺服器，通常放在 Authorization: Bearer … 或 X-Api-Key: … 中。伺服器金鑰會被瀏覽器阻止，也不會獲得 CORS 授權（CORS & Allowed Origins）。絕不要把伺服器金鑰放進使用者端，也不要把公開前端環境變數當作秘密儲存。
允許來源必須是沒有路徑和結尾斜線的純來源，例如 https://app.example.com，不能是 https://app.example.com/maps。除 localhost 或 127.0.0.1 本機測試外，Kaleidr 目前要求 HTTPS。來源必須精確比對：根域、www、app、admin 和預覽主機是不同來源。來源限制可減少瀏覽器中的未授權重複使用，但不能替代把伺服器機密資訊留在使用者端之外。
CORS、身分驗證、範圍和應用授權有何不同？
CORS 控制瀏覽器能否讀取跨來源回應；身分驗證識別呼叫端；範圍授權判斷憑證能否使用某項能力；宿主後端負責的應用授權決定哪個使用者或租戶可以造訪私有記錄。Kaleidr 的 CORS 流程可以允許預檢，但僅在來源核准時傳回 Access-Control-Allow-Origin；伺服器金鑰沒有瀏覽器 CORS 授權。401 通常表示憑證缺失、無效、過期或已撤銷；403 通常表示憑證有效但權限不足。Kaleidr 在金鑰有效但缺少路由所需能力時使用 insufficient_scope。診斷和監控時應將它們視為不同故障。
應如何建立、儲存、輪替和撤銷憑證？
應用最低權限，只授予每項整合所需範圍。Mapbox 建議把權杖範圍限制到最小，並在瀏覽器中只使用公開範圍；Google 同樣建議同時使用應用限制和僅覆蓋實際 API 的 API 限制。不要讓所有環境共享一個憑證，應分開開發、預覽和正式環境金鑰，以縮小影響範圍並簡化輪替。Mapbox 建議按環境或使用者端使用不同權杖；Google 建議每個應用使用不同 API 金鑰（權杖管理）。
新建立的 Kaleidr 金鑰值只顯示一次，應立即複製到機密資訊管理器。伺服器金鑰應儲存在機密資訊管理器或受保護的伺服器環境中，絕不能進入公開儲存庫或瀏覽器套件。CI/CD 應在部署時注入機密資訊，在記錄檔中遮蔽，並避免輸出環境轉儲。只記錄金鑰 ID、請求狀態和來源；對授權標頭與憑證值遮蔽。輪替時先建立替代金鑰並配置限制，部署後驗證流量，最後撤銷舊金鑰；若舊金鑰已外洩則應加速。配額也是安全控制：Platform API 按組織計量，流式端點限制並發（Quota & Rate Limits）。429 應與 401、403 分開處理，採用退避而不是重試風暴。
// Unsafe: never ship a server key to the browser
const SERVER_KEY = "YOUR_KALEIDR_SERVER_KEY";
// Safer browser pattern: publishable key + SDK session exchange
Kaleidr.mount("#map", {
publishableKey: "kld_pk_live_REPLACE_ME"
});
// Safer backend pattern: server key stays on the host
const response = await fetch("https://api.example.com/resource", {
headers: {
Authorization: `Bearer ${process.env.KALEIDR_SERVER_KEY}`
}
});
正式環境應用應如何分離平台身分驗證與宿主身分驗證？
推薦模式讓瀏覽器透過核准來源和公開金鑰使用公開 SDK 地圖功能，而已驗證的產品請求發送到宿主後端。後端管理使用者身分、租戶成員資格、物件授權、私有位置資料及機密資訊管理器中的伺服器金鑰，再發起伺服器間空間平台呼叫並只傳回核准欄位。公開金鑰不是終端使用者身分驗證，伺服器金鑰也不是資料庫資料列授權。Kaleidr 目前文件指出，已發布 Viewer 地圖由分享連結控制，無需 API 金鑰；仍應把分享連結視為存取控制，並避免透過不受限公共視圖發送私有資料。CSP 和安全 HTML 呈現是補充控制；Mapbox 警告，在彈出視窗中注入不受信任 HTML 會造成 XSS 風險，並建議對不受信任內容使用文字呈現。
團隊應避免哪些錯誤？
| 錯誤 | 風險 | 更好的做法 |
|---|---|---|
| 在 JavaScript 中發送伺服器金鑰 | 憑證遭竊 | 使用公開金鑰或後端代理 |
| 把 CORS 當成身分驗證 | 非瀏覽器呼叫端繞過假設 | 驗證每個受保護請求 |
| 到處使用同一金鑰 | 影響範圍很大 | 分離環境和應用 |
| 給每個金鑰全部範圍 | 權限過大 | 應用最低權限 |
| 在來源允許清單中新增路徑 | 來源比對失敗 | 使用 scheme://host[:port] |
| 記錄授權標頭 | 機密資訊外洩到記錄檔 | 對憑證遮蔽 |
| 把公開金鑰當作使用者身分 | 使用者無法區分 | 使用真正的終端使用者驗證 |
| 認為 API 驗證可保護私有資料列 | 租戶資料可能外洩 | 應用宿主授權 |
| 未檢查流量就輪替 | 正式環境中斷 | 撤銷舊金鑰前部署替代項 |
| 忽略 429 | 重試風暴和糟糕體驗 | 退避並監控配額 |
瀏覽器整合失敗時，先檢查來源拼寫、HTTPS 要求、金鑰類型、範圍和工作階段交換順序，再判斷平台故障。伺服器整合失敗時，檢查金鑰類型、環境、範圍、機密資訊注入及輪替期間是否誤撤銷。
最終結論
地圖 API 安全始於一項架構決定：瀏覽器和後端不能使用相同的憑證模型。瀏覽器需要可公開、受來源、範圍、工作階段期限或等效控制限制的憑證；後端需要留在受信任基礎設施中的機密資訊。再加入最低權限、環境隔離、應用授權、監控和輪替。Kaleidr 目前模型直接遵循這一模式：瀏覽器金鑰受來源限制，並由 SDK 換成短期工作階段；伺服器金鑰是用於伺服器間呼叫的 bearer 憑證，並被瀏覽器阻止。這條邊界比試圖把金鑰藏在前端程式碼中更重要。
使用 Kaleidr 文件保護地圖 API
部署前請檢查目前金鑰類型、能力範圍、來源規則和 API 行為。閱讀 Kaleidr Auth & Scopes，然後在開發人員文件中繼續了解 SDK 掛載和 Platform API 路由。
常見問題
什麼是地圖 API 驗證？
它是識別請求造訪地圖、地點、瓦片、路線或空間 API 的應用或服務的機制。常見機制包括 API 金鑰、存取權杖、工作階段、bearer 權杖和 OAuth。
API 金鑰能否安全用於瀏覽器？
只有提供方專門為使用者端設計時才可以。瀏覽器安全金鑰應受允許來源、公開範圍、應用限制或短期工作階段交換等限制。伺服器機密資訊絕不能放入瀏覽器程式碼。
公開 API 金鑰是機密資訊嗎？
不是。其安全性不應依賴字串保持隱藏，但仍需限制和監控。
伺服器 API 金鑰是機密資訊嗎？
是。它應留在受信任後端中，不能出現在 HTML、JavaScript 包、行動 WebView、公開儲存庫或使用者端儲存中。
CORS 是身分驗證嗎？
不是。CORS 控制瀏覽器能否讀取跨來源回應；身分驗證識別呼叫端；授權決定呼叫端能做什麼。
401 和 403 有何區別？
401 通常表示憑證缺失、無效、過期或已撤銷。403 通常表示憑證有效，但無權執行所請求操作。
開發和正式環境應使用不同 API 金鑰嗎？
是。分離憑證可縮小影響範圍、簡化來源限制、提高用量可見性並使輪替更安全。
應如何輪替 API 金鑰？
建立替代金鑰、配置限制、部署並驗證正式環境流量，然後再撤銷舊金鑰。若舊金鑰正遭外洩，應加速處理。
Kaleidr Viewer 需要 API 金鑰嗎？
目前文件指出，已發布 Viewer 地圖受分享連結控制，不需要 API 金鑰。
Kaleidr 如何保護瀏覽器整合？
目前模型使用帶允許來源清單的公開金鑰。SDK 將其換成與來源綁定的短期工作階段。伺服器金鑰會被瀏覽器阻止，僅用於伺服器間呼叫。
參考資料
IETF. HTTP Semantics (RFC 9110). RFC Editor. 於 2026年8月17日查閱. https://www.rfc-editor.org/rfc/rfc9110
IETF. The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). RFC Editor. 於 2026年8月17日查閱. https://www.rfc-editor.org/rfc/rfc6750
WHATWG. Fetch Standard. 於 2026年8月17日查閱. https://fetch.spec.whatwg.org/#http-cors-protocol
Google。Google Maps Platform 安全性指南。Google Maps Platform 文件。存取日期：2026年8月17日。https://developers.google.com/maps/api-security-best-practices
Kaleidr。Auth & Scopes。Kaleidr 開發人員文件。存取日期：2026年8月17日。https://docs.kaleidr.com/platform-api/auth-and-scopes
Kaleidr。CORS & Allowed Origins。Kaleidr 開發人員文件。存取日期：2026年8月17日。https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
Kaleidr。Quota & Rate Limits。Kaleidr 開發人員文件。存取日期：2026年8月17日。https://docs.kaleidr.com/platform-api/quota-and-rate-limits
Mapbox。安全使用 Mapbox。Mapbox 文件。存取日期：2026年8月17日。https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/
Mapbox。權杖管理。Mapbox 文件。存取日期：2026年8月17日。https://docs.mapbox.com/accounts/guides/tokens/
@misc{ietf_rfc9110_2026,
title = {HTTP Semantics (RFC 9110)},
author = {{IETF}},
note = {Accessed 17 August 2026},
url = {https://www.rfc-editor.org/rfc/rfc9110}
}
@misc{ietf_rfc6750_2026,
title = {The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)},
author = {{IETF}},
note = {Accessed 17 August 2026},
url = {https://www.rfc-editor.org/rfc/rfc6750}
}
@misc{whatwg_fetch_cors_2026,
title = {Fetch Standard},
author = {{WHATWG}},
note = {CORS protocol; accessed 17 August 2026},
url = {https://fetch.spec.whatwg.org/#http-cors-protocol}
}
@misc{kaleidr_auth_scopes_2026,
title = {Auth and Scopes},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 17 August 2026},
url = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}
@misc{kaleidr_cors_origins_2026,
title = {CORS and Allowed Origins},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 17 August 2026},
url = {https://docs.kaleidr.com/platform-api/cors-and-allowed-origins}
}
@misc{kaleidr_quota_2026,
title = {Quota and Rate Limits},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 17 August 2026},
url = {https://docs.kaleidr.com/platform-api/quota-and-rate-limits}
}
@misc{mapbox_token_management_2026,
title = {Token Management},
author = {{Mapbox}},
note = {Accessed 17 August 2026},
url = {https://docs.mapbox.com/accounts/guides/tokens/}
}
@misc{mapbox_secure_2026,
title = {How to Use Mapbox Securely},
author = {{Mapbox}},
note = {Accessed 17 August 2026},
url = {https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/}
}
@misc{google_maps_security_2026,
title = {Google Maps Platform Security Guidance},
author = {{Google}},
note = {Accessed 17 August 2026},
url = {https://developers.google.com/maps/api-security-best-practices}
}