管理

API金鑰與OAuth客戶端

為指令碼與CI建立限定範圍的API金鑰、為代表使用者行動的應用程式註冊OAuth客戶端，並在用完後撤銷任一種。

Polylane有兩種供程式化存取使用的憑證類型。API金鑰適合指令碼、CI與無瀏覽器環境的工具：一把金鑰、一個工作區、一組固定的範圍。OAuth客戶端適合讓使用者登入並代表他們呼叫Polylane的應用程式，兩者都針對同一個API驗證。

API金鑰

在主控台開啟Settings > API Keys並點擊Create an API key。為金鑰命名（至少4個字元）並挑選它的範圍：表單會預選你自己的成員身分所持有的範圍，請求一個你未持有的範圍會以403失敗。金鑰只顯示一次，以sk_開頭且無法再次檢視，所以請把它複製到你的密鑰管理工具。

在x-api-key標頭中送出金鑰：

Terminal

curl https://api.polylane.com/v1/scopes \
  -H "x-api-key: sk_xxxxx"

請求依金鑰的範圍授權，而不是你的完整權限。從同一個設定頁面撤銷金鑰，或對/v1/api_keys/{workspaceId}/{id}發出DELETE；金鑰的建立者或工作區管理員可以刪除它。

範圍

範圍把一個資源與一個動作配對，GET /v1/scopes列出每一個範圍及其說明。以下是你在這些文件中最常遇到的範圍。

範圍	說明
`threads:read`	檢視對話串。
`issues:write`	確認、解決或重新執行問題檢查。
`cloud_infra:read`	檢視雲端基礎設施節點與邊。
`autofixes:write`	記錄並更新Autofix生命週期狀態。
`agent_tools:read`	從MCP等外部客戶端探索並執行唯讀代理工具。
`agent_tools:write`	從外部客戶端執行具寫入能力的代理工具，需經安全審查。
`oauth_clients:write`	建立並管理OAuth客戶端。
`analytics:read`	檢視工作區活動、熱門內容與用量統計。

OAuth客戶端是你註冊的應用程式，讓它可以讓使用者登入，並以每位使用者核准的範圍呼叫Polylane；管理客戶端需要oauth_clients:write。開啟Settings > OAuth Clients並點擊New OAuth client：名稱與聯絡電子郵件會出現在同意畫面上，你加入重新導向URI與客戶端可以請求的範圍，描述、網站與標誌則是選填。建立後會回傳一個以oauth_client_開頭的客戶端ID與一個只顯示一次的客戶端密鑰；如果你遺失了密鑰，在客戶端頁面Rotate它，先前的密鑰會立即失效。

授權流程

Polylane實作帶有PKCE（S256）的OAuth 2.0授權碼流程。

把使用者送到同意頁面

https://console.polylane.com/oauth/<client-id>
  ?client_id=<client-id>
  &redirect_uri=https://example.com/callback
  &scope=threads:read%20issues:read
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &state=<random-state>

重新導向URI必須與你註冊的其中一個完全一致，且每個請求的範圍都必須是客戶端已被授予的。

用授權碼換取權杖

使用者核准後，Polylane會帶著code重新導向到你的回呼。在你的後端交換它：

Terminal

curl -X POST https://api.polylane.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "<code>",
       "redirect_uri": "https://example.com/callback",
       "client_id": "<client-id>", "client_secret": "<client-secret>",
       "code_verifier": "<verifier>"}'

回應帶有一個一小時後到期的access_token與一個refresh_token。

以使用者身分呼叫API

Terminal

curl https://api.polylane.com/v1/scopes \
  -H "Authorization: Bearer <access-token>"

存取權杖到期時刷新

向同一個權杖端點送出grant_type為refresh_token的請求。刷新權杖是一次性的：每次刷新都會回傳一個替代的權杖。

伺服器中繼資料，包括每個端點的URL，發布在https://api.polylane.com/v1/.well-known/oauth-authorization-server，提供者也公開/v1/oauth/userinfo與/v1/oauth/introspect。要撤銷你的應用程式持有的權杖，對/v1/oauth/revoke發出帶有該權杖與你客戶端憑證的POST，token_type_hint設為access_token或refresh_token，或省略以兩者都嘗試。從客戶端頁面刪除客戶端會使它無法再開始新的授權。

程式碼代理

連接程式碼代理不需要OAuth客戶端。位於https://mcp.polylane.com/mcp的託管MCP伺服器執行自己的、支援動態客戶端註冊的OAuth流程，也接受API金鑰；請見平台MCP伺服器。