API 身份验证

Showly REST API 接受两类凭证。请根据使用场景选择。基础 URL 为 https://api.showly.ai，没有版本前缀，也不使用 Api-Version 请求头。

个人访问令牌 (PAT)

适用于： 临时脚本和个人自动化。

在个人资料 → API 令牌 → 新建令牌中签发。PAT 只属于创建它的 单个工作区，并包含创建时授予的作用域。请像保护密码一样保护它。

GET /sites HTTP/1.1
Host: api.showly.ai
Authorization: Bearer sk_live_...

PAT 使用 sk_live_ 前缀，沙箱环境使用 sk_test_。PAT 具有以下特性：

• 审计日志会把操作归因到签发令牌的用户。
• 每个令牌只绑定一个工作区；自动化涉及多个工作区时，应分别创建。
• 可在同一界面撤销或轮换。用于 CI 时，请为每条流水线使用独立 PAT

并定期轮换。

MCP 令牌（设备授权流程）

适用于： 代表用户操作的智能体和 MCP 客户端，例如 Claude Code、Codex。

智能体客户端使用 RFC 8628 设备授权流程获得 MCP 令牌。令牌绑定到 完成授权的用户，并且只包含用户同意的作用域。MCP 令牌使用 mcp_live_ 前缀，沙箱环境使用 mcp_test_。

通过请求设备代码来启动流程：

POST /oauth/device
Content-Type: application/x-www-form-urlencoded

client_id=<your-app>
&scope=site:read preview:create

用户在浏览器中批准请求（设备流查找/授权端点返回验证页面）。同时，使用设备代码轮询令牌端点，直到用户完成批准：

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=<device-code>
&client_id=<your-app>

授权完成后会签发 MCP 令牌。注意：POST /oauth/token 直接返回 RFC 6749/8628 响应体（{ "access_token", "token_type": "Bearer", "scope" }）， 不使用标准 { ok, data } 外层结构，因此不要按 ok 字段分支。 作用域使用规范的 resource:verb 命名，例如 site:read、 preview:create。完整清单见作用域和令牌， REST 与 MCP 使用同一套作用域。

没有 grant_type=refresh_token 端点。要续订 MCP 令牌，请轮换它：POST /admin/mcp-tokens/:tokenId/rotate。

明智地选择