权限范围明确，控制始终在你

连接就是工作区令牌

工作区所有者和管理员，在开发者页面创建连接。每个连接都是绑定到一个工作区和一种使用对象的 Bearer 令牌：rest 令牌（sw_rest_...）只能用于 /api/v1，mcp 令牌（sw_mcp_...）只能用于 /mcp。

在 Authorization 标头中发送令牌。绝不要把它放进 URL、查询字符串、导入文件或浏览器打包资源中。

Authorization: Bearer sw_rest_...

权限范围进一步收窄角色权限

新连接默认只有只读权限：workspaces:read、catalog:read 和 worlds:read。只添加任务所需的权限，例如用 worlds:write 编辑草稿，或用 worlds:publish 发布。GET /me 需要 account:read。

权限范围绝不会赋予超过令牌创建者自身能力的权限，而且每次请求都会重新读取该角色。其他工作区的 id 返回 404，因此令牌无法探知无权查看的内容。

敏感权限需主动选择

涉及订阅者邮箱、访客消息、账单、删除、DNS 写入、支出、团队更改或 webhook 的权限范围，绝不会默认勾选。添加这些权限前，会要求你重新登录。在令牌获得相应权限之前，其 MCP 工具会保持隐藏。

有些操作始终不对令牌开放：决定是否批准、删除或恢复小屋和账户（这些需要重新通过第一方登录验证，并返回 403 reauthentication_required），以及数据导出。

到期、轮换与撤销

• 令牌默认30天后过期，最长有效期为90天。
• 系统只存储哈希值，因此丢失的令牌无法再次显示。请改为创建新连接。
• 轮换时，先创建新连接，将客户端切换过去，再撤销旧连接。撤销从下一次请求起生效，也包括智能体已经排队的工作。

可能遇到的错误

• 401：令牌缺失、未知、已过期、已撤销，或用于另一种使用对象。
• 403 insufficient_scope：令牌缺少权限。context.required_scope 会指出所需权限，响应还带有 WWW-Authenticate 标头。
• 404：资源不存在于该令牌的工作区中。

OAuth 尚不可用

只支持 OAuth 登录的智能体客户端，目前还无法连接。因此，/.well-known/oauth-protected-resource/mcp 不列出任何授权服务器。请改为在客户端的标头设置中使用连接令牌。