OAuth API

代理 JWT 的 OAuth 2.0 令牌端点（RFC 6749 §3.2）。grant_type refresh_token 轮换不透明刷新凭证（RFC 9700）：每次使用返回一对新凭证；request_id（16 到 200 字符）使得在凭证和授权仍有效且后继仍是当前时，完全重试返回相同响应，无需超时重试。

任何对已废止刷新令牌的其他重用都会撤销整个系列（invalid_grant）。被移除的选定成员或项目返回invalid_scope，error_description以"project_selection_inactive:"开头；刷新凭证不被消耗。

通过 GET /api/projects 发现实时成员资格，将其与先前同意的选择交集，并使用 projects= 和新的 request_id 重试。永远不要因此选择错误结束刷新系列。

请求的权限范围缩小独立适用于每个项目和身份权限；明确指定范围但无身份则排除身份权限。grant_type urn:ietf:params:oauth:grant-type:token-exchange（RFC 8693）且 subject_token_type 为 urn:screenrig:token-type:identity-credential 或 urn:screenrig:token-type:project-token 时，返回 unsupported_token_type：旧凭证已废弃，安装程序需使用 screenrig login 重新登录。resource（RFC 8707）为 https://api.<domain>/api 或无；projects 选择最多 64 个已同意的项目 ID。

省略仅在集合适合时选择全部；否则客户端必须选择子集。project_id 在兼容性发布期间选择一个。连接应用的授权仅含单一资源 https://api.<domain>/mcp，刷新时可能省略。

客户端分为公开客户端（仅 client_id）或连接应用，其元数据声明 private_key_jwt 通过 client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer 和 client_assertion（iss 和 sub 为其 client_id，aud 为发行者或此端点的字符串，exp 在 iat 后 5 分钟内，jti 唯一使用，kid 指定其密钥之一；支持 EdDSA、ES256 或 RS256）进行认证。grant_type authorization_code 在 60 秒内使用精确 redirect_uri 和 PKCE code_verifier 兑换连接应用的代码；resource 必须为空或授权的那个；第二次兑换会撤销该代码创建的授权。grant_type client_credentials 是服务客户端：通过客户端断言（其注册密钥之一）或 HTTP Basic（client_secret_basic；请求体中的密钥被拒绝）认证，获得 15 分钟的服务令牌，适用于其项目、受众 api 或（资源 https://api.<domain>/mcp）mcp，权限在其能力和访问级别内，无刷新令牌；每客户端每小时限 600 次。

错误为 RFC 6749 JSON {error, error_description}，带 Cache-Control no-store；服务器未发出时返回 temporarily_unavailable (503)。

速率限制返回 429 rate_limited，带 Retry-After：本端点及撤销端点每客户端地址每小时 1200 次，每授权每小时 60 次刷新，每旧凭证每小时 30 次交换。grant_type urn:ietf:params:oauth:grant-type:device_code（RFC 8628 §3.4）轮询设备登录：等待授权时返回 authorization_pending，轮询过快返回 slow_down（间隔增加 5 秒），拒绝时返回 access_denied，10 分钟后返回 expired_token，然后返回令牌响应。

新安装接收一对令牌；使用现有安装的访问令牌启动的登录将批准项目添加到该授权，并仅接收访问令牌，不旋转刷新令牌。再次轮询相同 device_code 返回相同响应，直到授权首次旋转或 10 分钟后返回 invalid_grant。

仅限 POST，表单编码，无查询字符串。

RFC 8628 §3.1 设备授权针对 `screenrig login`。scope 为 access:manage（默认）、access:propose 或 access:read；project_id 建议用户批准的项目；name、agent_type、platform 和 version 描述安装，由设备报告并显示给审批者；install_source（可选）说明其安装来源，并保存在批准所创建的智能体上。

无 Authorization 时启动新安装。使用 Authorization: Bearer 和带有身份范围的智能体访问令牌请求将项目添加到该安装的授权，或将只读项目提升为管理权限。

该人员在 verification_uri（或访问 verification_uri_complete）输入 user_code 并在仪表板批准；设备每隔若干秒使用 device_code 轮询令牌端点。

速率限制返回 429 rate_limited，带 Retry-After：每客户端地址每小时 10 次，每小时全局 600 次，端点后为每地址每小时 1200 次。错误为 RFC 6749 JSON，带 Cache-Control no-store；服务器未发出时返回 temporarily_unavailable（503）。仅支持 POST，表单编码，无查询字符串。

连接应用的 OAuth 2.0 授权端点（MCP 客户端）。client_id 是客户端 ID 元数据文档 URL（https，端口 443，无重定向，最大 64 KiB 和 5 秒，仅限公共地址）或注册的客户端 ID。

请求按以下顺序验证：客户端、精确的 redirect_uri（指向 127.0.0.1、[::1] 或 localhost 的 http 回环重定向在任意端口都匹配）、response_type code、带 code_challenge_method S256 的 code_challenge、resource（https://api.<domain>/mcp、受保护资源元数据指明此服务器的其他 MCP 资源，或省略），然后是 scope（access:read（默认）、access:propose、access:manage 和能力名称）。

未知客户端或redirect_uri返回HTML错误页面且不重定向；之后的错误会重定向到redirect_uri，带有error、error_description、state和iss（RFC 9207）。

成功响应 303 到仪表板同意页面，用户选择项目、访问级别（默认只读，提议或管理）和权限；批准后重定向带有代码、状态和发行者。每个客户端地址每分钟限 30 次请求。

RFC 7009 撤销。向客户端发放的不透明刷新凭证（或先前版本的刷新 JWT）或代理访问 JWT，撤销其授权；授权的访问令牌将在数秒内被拒绝。未知、过期或外来令牌也返回 200。仅支持 POST，表单编码。

RFC 8414 代理授权服务器的授权服务器元数据。

RFC 9728 /mcp 的受保护资源元数据，由每个 /mcp 401 的 resource_metadata 命名。

RFC 9728 /api 的受保护资源元数据。

待处理的连接应用授权，用于同意页面：客户端名称和域名按其元数据声明（不获取徽标），是否为注册客户端，重定向主机，以及请求的访问级别和功能。未知、过期或已处理的授权返回 not_found。

在新证明（类型 oauth_authorization_approval，主题为授权 ID）后批准某人项目的已连接应用：创建应用的智能体身份（类型 mcp_client，负责人为该人）、其成员身份及所选访问权限（读或管理；省略则保持请求级别，默认读）和能力（请求的子集），并响应 redirect_uri，携带 code、state 和 iss，页面据此导航。

该代码有效期为 60 秒。限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

在新的证明后拒绝已连接的应用（kind oauth_authorization_denial），并返回页面要跳转的 redirect_uri，其中携带 error=access_denied、state 和 iss。限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。