身份驗證

只需一個標頭，除自我描述的索引頁外，每個請求都要附上。

Authorization: Bearer <your api key>

Token 在您的帳戶頁面建立——每個帳戶最多十個，每個均可單獨撤銷，因此即使其中一個洩露，也可刪除它而不影響其他 Token。必須擁有付費方案：沒有付費方案時，除 / 及 /v1/account 外，所有端點都會返回 403 plan_required。

應用程式也可以透過 OAuth 2.1 代您取得 Token：您登入、查看它要求的權限，然後按「允許」。它的 Token 放在同一個標頭中，用法完全相同。

為何不用 ?key=

放在查詢字串中的 Token 會出現在您意想不到的地方：網頁伺服器的存取日誌、瀏覽器記錄、代理伺服器日誌，以及回應中任何連結所帶的 Referer 標頭。因此 API 不接受這種寫法，並會返回 401 missing_key 加以說明。

主網站上的舊版 ?export= 網址仍然接受 ?key=，因為多年前寫成的腳本依賴它，取消它會令這些腳本失效。這是唯一仍接受它的地方——請參閱舊版匯出網址。

檢查 Token 是否有效

/v1/account 是最省的呼叫：它不消耗任何配額，即使帳戶沒有方案也能使用，因此可同時回答「這個 Token 是否有效」和「我可以使用哪些功能」。

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

可能出現的錯誤

401 回應亦會附帶 WWW-Authenticate: Bearer 標頭，讓以通用方式處理身份驗證的 HTTP 用戶端能作出合理反應。

供應用程式使用的 OAuth 2.1

代表其他人運作的應用程式——例如助理、整合服務或託管服務——不應要求每個用戶複製 Token，而應把他們帶到 PublicWWW：用戶登入、批准該應用程式，應用程式便會獲得自己的 Token。這個 Token 與其他 Token 一樣以 Authorization: Bearer 發送，可使用整個 API 及位於 https://api.publicwww.com/mcp 的 MCP 伺服器，並受該帳戶的方案、配額及速率限制約束。

識別應用程式

本站不設用戶端註冊。client_id 就是應用程式所發佈的一份小型 JSON 文件的 https 網址——即用戶端中繼資料文件（client metadata document）。每次有人連接時，PublicWWW 都會讀取這份文件，因此名稱及返回位址永遠是最新的，而批准的人也能看到是哪個主機發佈了這些資料。

{
  "client_id": "https://app.example.com/oauth/client.json",
  "client_name": "Example App",
  "redirect_uris": ["https://app.example.com/oauth/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

• 文件內的 client_id 必須與提供該文件的網址完全相同。文件會經 https 從包含路徑的網址取得，且不跟隨重新導向；文件必須在 5 秒內回應，大小須少於 64 KB。
• redirect_uris 必須是 https 位址；如應用程式在用戶自己的電腦上運行，則可使用 127.0.0.1、localhost 或 [::1] 上的 http 位址——此時任何連接埠均可符合。不接受 myapp:// 之類的自訂協定。
• 所有應用程式都是公開用戶端：無論文件中的 token_endpoint_auth_method 寫的是什麼，Token 請求都不帶任何密鑰。授權碼改由 PKCE 保護。

流程

採用附 PKCE 的授權碼流程；只支援 S256 方法。把用戶帶到授權端點：

https://publicwww.com/oauth/authorize
    ?response_type=code
    &client_id=https%3A%2F%2Fapp.example.com%2Foauth%2Fclient.json
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
    &code_challenge=<BASE64URL(SHA-256(code_verifier))>
    &code_challenge_method=S256
    &state=<random>

如用戶尚未登入，會先以電郵收到的一次性驗證碼登入，然後看到應用程式的名稱、其文件所在的主機以及將返回的位址，再按「允許」或「取消」。返回 redirect_uri 時會帶上 code、您的 state 及 iss=https://publicwww.com（RFC 9207）。授權碼有效期為十分鐘，且只能使用一次。以它換取 Token：

curl https://publicwww.com/oauth/token \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d code_verifier="$VERIFIER" \
     -d client_id=https://app.example.com/oauth/client.json \
     -d redirect_uri=https://app.example.com/oauth/callback

{ "access_token": "<token>", "token_type": "Bearer", "scope": "mcp" }

scope 可以省略：只有一個範圍 mcp，涵蓋整個 API。resource（RFC 8707）亦可省略；如有提供，其值須為 https://api.publicwww.com/mcp 或 https://api.publicwww.com。

Token 的有效期

直至被撤銷為止——沒有到期時間，也沒有更新 Token（refresh token）。今天能運作的整合，明天無須任何人處理也能照常運作。Token 只會因刻意的操作而被撤銷：用戶在其帳戶頁面解除連接該應用程式、應用程式自行撤銷，或帳戶被刪除。

curl https://publicwww.com/oauth/revoke \
     -d token="$TOKEN" \
     -d client_id=https://app.example.com/oauth/client.json

無論 Token 是否存在，撤銷端點一律返回 200。

OAuth 錯誤

除錯誤頁面外，授權錯誤會以 error、error_description、state 及 iss 送回 redirect_uri；Token 錯誤則是 400 回應，在 JSON 中帶有同樣兩個欄位。