管理

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`	记录和更新自动修复生命周期状态。
`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和客户端可以请求的权限范围，描述、网站和logo是可选的。创建后返回一个以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服务器。