如何在 Mintlify 中設定私有 API 文件的閘道存取與使用者身分驗證

對於維護面向企業客戶、付費合作夥伴或特定生態整合商的技術架構師與文件團隊而言，私有 API 文件的發布往往面臨安全與體驗的平衡挑戰：一方面，團隊期望善用 Mintlify 強大的 MDX 與 OpenAPI 引擎，打造兼具現代感與互動性的 API 參考指南和線上 Playground；另一方面，核心內部介面、專屬計費端點與內部 SDK 又必須嚴格隔離，防止公開搜尋引擎爬取與非授權存取。

Mintlify 透過靈活的存取控制機制化解了這個難題，支援四種主要驗證模式：組織成員內部存取、全站密碼保護、企業級單點登入（SSO / OAuth 2.0）以及自訂 JWT（JSON Web Token）權杖驗證。本文將深入探討私有文件的網域限制、設定工作流程、頁面層級群組授權（RBAC）以及互動式 Playground 憑證預填機制，協助工程團隊快速建立合規且安全的私有文件體系。

核心架構前提與網域限制

在開始設定身分驗證前，工程團隊必須先釐清 Mintlify 對於受限內容的部署限制：

1. 獨立網域託管要求： 無論是全站驗證還是部分驗證，Mintlify 皆要求文件必須託管於專用自訂網域（例如 docs.api.example.com）或 Mintlify 子網域（例如 example.mintlify.site）。不支援基於子路徑（如 example.com/docs）的閘道身分驗證。若受限於子路徑架構，僅能採用無法強制阻擋存取的客戶端個人化（Personalization）方案。
2. 存取隔離範圍（全站 vs. 部分驗證）： 團隊可在後台選擇全站驗證（Full Authentication）（全站所有頁面與 OpenAPI 規格皆須登入才能檢視）或部分驗證（Partial Authentication）（公開快速上手指南，僅對核心商業 API 與私密章節實施登入防護）。
3. 預覽部署（Preview Deployments）安全： 當透過 Git 整合由 PR 觸發預覽站點時，未受保護的預覽連結可能成為端點外洩的破口。在 Mintlify 後台啟動驗證功能後，所有預覽部署亦會自動繼承安全閘道防護。

身分驗證機制比較矩陣

方式一：全站密碼保護（輕量級快速隔離）

若目前處於邀請少數戰略夥伴參與封測，或受保密協議限制的早期階段，密碼保護可在無須串接任何身分識別提供者（IdP）的情況下建立存取門檻。

設定步驟

1. 登入 Mintlify 控制台，進入專案的 Access（存取控制）分頁。
2. 將 Visibility（可見度）由 Public 切換為 Private。
3. 將驗證方式 Method 選擇為 Password。
4. 輸入高強度的共用密碼，並點擊 Save changes 儲存套用。

架構考量與限制

此方式只需兩分鐘即可完成，但因所有人共用單一密碼，系統無法產生日誌審計個別使用者的閱讀行為，無法依角色劃分權限，且當合作夥伴人員異動時，必須更新全站密碼。因此，密碼保護僅建議用於暫時性質的預覽環境。

方式二：企業單點登入與 OAuth 2.0（身分聯合驗證）

針對內部工程團隊內部參考或面向大型企業客戶的場景，透過 SAML 2.0 或 OAuth 2.0 串接企業現有的 IdP，不僅符合資安法規要求，亦能實現即時的使用者權限控管。

Okta SAML 2.0 整合流程

1. 取得 Mintlify 端點資訊： 在 Mintlify 控制台進入 Security 頁面，點選 Configure 並選擇 Okta SAML。複製系統提供的 Single sign on URL（ACS 網址）與 Audience URI（實體識別碼）。
2. 在 IdP 建立 SAML 應用： 進入 Okta 管理後台，選擇 Applications > Create App Integration > SAML 2.0，貼上第一步取得的 URL 與 URI。
3. 對應使用者屬性宣告： 依據 Mintlify 格式設定屬性對應：
   • firstName 對應至 user.firstName；
   • lastName 對應至 user.lastName；
   • Name 對應至 user.email，並將 Name ID 格式設為 EmailAddress。
4. 回傳中繼資料完成綁定： 從 Okta 複製 Metadata URL（中繼資料網址），貼回 Mintlify 控制台的相應欄位，點選 Save changes 完成設定。

啟用後，所有連線至文件網域的請求皆會被自動導向企業 IdP 進行身分驗證，通過後方可讀取私有 API 規格。

方式三：以 JWT 為基礎的自訂驗證（主站無縫銜接）

在現代化 SaaS 服務中，合作夥伴通常已在您的主站控制台（Console）完成身分識別。為了提供無摩擦的開發者體驗，Mintlify 支援基於非對稱簽章的 JWT 權杖橋接模式。

互動時序圖

開發者瀏覽器                   主站服務後端 (Your Backend)         Mintlify 文件網站
     |                                |                                   |
     | 1. 於主站點擊「專屬 API 文件」   |                                   |
     |------------------------------->|                                   |
     |                                | 2. 注入使用者角色與權限資訊，       |
     |                                |    使用 ES256 私密金鑰簽署 JWT     |
     | 3. 重新導向至文件網址 Hash 錨點  |                                   |
     |    https://docs.example.com/#JWT|                                  |
     |<-------------------------------|                                   |
     |                                                                    |
     | 4. 帶著 URL Fragment 中的 JWT 請求文件頁面                         |
     |------------------------------------------------------------------->|
     |                                | 5. 驗證 ES256 簽章，              |
     |                                |    解析群組並清除網址列中的 Hash    |
     | 6. 呈現對應權限之私有介面與預填 Playground                          |
     |<-------------------------------------------------------------------|

具體實作步驟

1. 在 Mintlify 控制台進入 Access（或 Personalization）設定，選擇 JWT 模式，並填寫主站的登入導向網址。
2. 於控制台產生專屬金鑰對，並將 Mintlify 分配的私密金鑰安全儲存於伺服器端環境變數或密鑰保管庫（KMS）。
3. 當後端接收到導向請求時，建構包含使用者宣告、有效期限及角色分組的 Payload，並使用 ES256 演算法簽署：

import jwt from "jsonwebtoken";

// Node.js 後端簽署 Mintlify 身分驗證 Token 範例
export function generateMintlifyDocToken(user, partnerAccount) {
  const payload = {
    // 標準 JWT 宣告
    sub: user.id,
    exp: Math.floor(Date.now() / 1000) + 10, // 極短有效期限：10秒以內
    
    // Mintlify 專屬工作階段有效期限欄位
    expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8), // 8小時本地登入期
    
    // 供 MDX 條件式渲染使用的上下文
    content: {
      userId: user.id,
      email: user.email,
      organization: partnerAccount.name,
      plan: partnerAccount.tier // 例如 "enterprise" 或 "vip-partner"
    },
    
    // 用於導覽列過濾與頁面存取限制的群組權限
    groups: [partnerAccount.tier, "partner-tier-1"],
    
    // 自動預填 API Playground 的測試金鑰
    apiPlaygroundInputs: {
      header: {
        Authorization: `Bearer ${partnerAccount.ephemeralSandboxKey}`
      }
    }
  };

  return jwt.sign(payload, process.env.MINTLIFY_PRIVATE_SIGNING_KEY, {
    algorithm: "ES256"
  });
}

4. 將前端重新導向至文件頁面時，將簽署完成的 JWT 附加於 URL Fragment（Hash）之後：

   https://docs.api.example.com/api/v2/private-settlement#eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
   

   Mintlify 前端會自動擷取 Hash 中的權杖，以已登記的公開金鑰完成校驗並建立本地工作階段，隨後立即透過瀏覽器 History API 清除該 Hash，防止權杖外洩或遭惡意側錄。

角色型存取控制（RBAC）與頁面層級隔離

身分驗證完成後，工程團隊需依合作夥伴等級進行精確的內容劃分。

1. MDX Frontmatter 頁面權限隔離

在敏感端點對應的 .mdx 文件頂端加入 groups 宣告：

---
title: "合作夥伴清結算 Webhooks"
description: "專屬大型結算機構的高吞吐量支付通知規格"
groups: ["enterprise", "fintech-partners"]
---

若造訪者的 JWT 或 SSO 屬性中未包含指定的群組代碼，Mintlify 將在側邊導覽列中徹底隱藏該文件，並在直接存取該 URL 時回傳存取受限（404 或攔截畫面）。

2. MDX 內透過 userContext 實施動態區塊渲染

針對共用頁面中少數專屬段落，可直接調用 userContext 實施條件式渲染：

# 平台呼叫速率與配額規則

{userContext?.content?.plan === "enterprise" ? (
  <Card title="專屬企業頻寬" icon="shield-check">
    您的方案享有專屬 10,000 QPS 頻寬與專屬 SLA 支援。
  </Card>
) : (
  <Card title="標準限流規則" icon="gauge">
    標準開發者配額為每分鐘 200 次請求。如需提升配額，請洽詢企業業務團隊。
  </Card>
)}

3. 人類使用者與 AI Agent 內容隔離

Mintlify 預設會輸出 Markdown 格式供 LLM 與 AI 工具檢索。若某些專屬整合提示不宜暴露給 AI 工具爬取，可使用 <Visibility> 元件進行隔離：

<Visibility for="humans">
  <Note>正式環境金鑰請務必每 90 天於管理平台手動輪替一次。</Note>
</Visibility>

<Visibility for="agents">
  API 請求需於 Authorization 標頭中夾帶 Bearer Token。
</Visibility>

互動式 API Playground 安全防護

Mintlify 的互動式線上呼叫區（Playground）極具價值，但若防護不當，可能導致正式金鑰外洩或跨租戶存取風險。

1. 透過 apiPlaygroundInputs 安全預填金鑰

避免要求合作夥伴從管理後台手動複製敏感金鑰，改由驗證工作階段自動注入沙盒環境權杖：

{
  "apiPlaygroundInputs": {
    "server": {
      "environment": "sandbox"
    },
    "header": {
      "Authorization": "Bearer sbx_partner_9981aef0"
    },
    "query": {
      "version": "2026-10"
    }
  }
}

Mintlify 會在 Playground 載入時將上述數值動態綁定至請求標頭與查詢參數。

2. 安全最佳實踐

• 強制指向隔離沙盒： 在 docs.json 定義的 OpenAPI 伺服器網址中，Playground 預設值必須指向沙盒或 Mock 節點，嚴禁直連正式環境。
• 杜絕長期主金鑰注入： apiPlaygroundInputs 所提供之金鑰必須具備短期有效性，並在 API 閘道層限縮至最小測試權限。
• 使用 OpenAPI x-default 作為備用預設值： 若在未啟用動態 JWT 的公開頁面中，請於 OpenAPI securitySchemes 中使用 x-default 宣告佔位符（如 x-default: "YOUR_SANDBOX_KEY"），嚴禁將測試金鑰寫死於程式碼庫中。

上線檢查清單

• 獨立網域確認： 確認文件部署於獨立子網域（如 docs.partner.example.com），而非不支援閘道驗證的子路徑（/docs）。
• 驗證範圍確認： 依據公開需求，於 Access 設定頁明確啟用全站驗證（Full）或部分驗證（Partial）。
• 金鑰安全控管： ES256 簽章私密金鑰已存放於密鑰管理系統（KMS），未簽入 Git 儲存庫。
• 權杖有效期限： JWT 之 exp 宣告設定於 10 秒以內，以防範重放攻擊。
• 分組標籤完整： 私有端點 MDX 皆已完整配置 groups 標籤。
• 除錯環境降權： 互動式 Playground 已設定為僅能存取沙盒或 Mock 環境。
• 預覽部署隔離： 已確認 Git PR 預覽環境已套用相同的身分驗證規則。

落實上述架構規劃與防護措施，工程團隊即可為重要合作夥伴提供卓越的現代化互動文件體驗，同時維持私有 API 零信任架構的嚴密防線。

參考資料

• Authentication setup - Mintlify
• SSO - Mintlify
• Personalized content - Mintlify