存取控制
Powerduck 把讀者如何存取文件與用戶端如何存取 MCP 端點分開，因為兩者的消費方式不同。它還配置 MCP 伺服器如何向上游 API 認證。
各關卡（按順序）
若干條件決定一個公開面是否打開。知道完整清單能回答那個常見問題：「為什麼我打不開我的文件？」
- 文件狀態——文件必須為
ACTIVE（未暫停、歸檔或刪除）； - 形態已啟用——文件用
documentationEnabled，MCP 用mcpEnabled； - 存取憑據——配置後，文件用檢視密碼，MCP 用存取密鑰；
- 有效期——文件檢視可設定在指定時間過期。
形態背後的已發布產物在你新增版本或變更暴露後自動建構，因此發布通常不是手動步驟。
每個形態相互獨立：停用 MCP 不影響文件，文件密碼也不為 MCP 把關。
文件檢視密碼
檢視密碼保護渲染文件和所提供的規範資料：
- 密碼用 scrypt 配合每個密碼隨機的鹽進行雜湊；不儲存明文；
- 設定密碼後，讀者必須先提供它，文件才會被提供；
- 密碼只為文件把關；MCP 端點使用自己的存取密鑰並跳過檢視密碼。
你還可以設定檢視有效期。過期之後，即使密碼正確也會拒絕存取。清除密碼或有效期即可移除限制。
MCP 端點存取密鑰
MCP 端點用自己的存取密鑰保護：
- 產生（或輪換）密鑰；完整密鑰僅回傳一次，之後只顯示最後四個字元；
- 配置密鑰後，每個 MCP 請求必須以
Bearer權杖呈現它； - 提供的密鑰以恆定時間比較，缺失或錯誤的密鑰回傳
401。
刪除密鑰可讓 MCP 端點開放（前提是文件活動且 MCP 啟用）。
MCP 上游認證
除了為端點把關之外，還可以配置 MCP 伺服器如何向規範所描述的上游 API 認證。支援的認證類型為：
authType | 配置 |
|---|---|
NONE | 無上游認證 |
BEARER | 一個 Bearer 權杖 |
BASIC | 基本認證的使用者名稱和密碼 |
APIKEY | API 密鑰名稱（請求頭/查詢）和值 |
Bearer 權杖、基本認證密碼和 API 密鑰值等機密可以寫入但從不會被讀回；配置只報告它們是否已設定。
其他 MCP 配置包括：
- 基礎 URL 覆蓋——覆蓋上游基礎 URL，而不是從規範取得；
- 請求逾時——MCP 伺服器呼叫上游 API 時使用的逾時。
推薦設定
- 公開文件： 啟用文件，開放 API 可不開密碼，或為受控分享設定密碼和有效期；
- 給自己代理用的 MCP ： 啟用 MCP 並產生存取密鑰，讓只有你的用戶端能呼叫；
- 上游認證： 讓 MCP 伺服器的認證匹配真實 API 的要求，獨立於誰可以呼叫 MCP 端點。