Skip to main content
对 Square Cloud API 的每个请求都要携带一个 API 密钥。请在账户安全设置中创建密钥：每个账户最多可拥有 10 个密钥，每个密钥都有名称，新密钥的密文只会显示一次。在那里创建的密钥不会过期。CLI 和 VS Code 扩展在连接时获得的密钥有效期为 90 天。

​
发送密钥

在 Authorization 请求头中发送密钥。Bearer 前缀是可选的。
请将密钥保存在服务器上的环境变量中。任何持有该密钥的人都可以在其权限范围内操作你的账户。API 的使用受服务条款和可接受使用政策的约束。
更喜欢类型化的客户端？适用于 JavaScript、Python 和 Go 的 Square Cloud SDK 会替你发送密钥，并封装了本参考中的每个端点。

​
权限范围

每个密钥都带有权限范围（scope），决定它可以执行哪些操作。完全访问权限的密钥涵盖所有权限范围，包括日后新增的权限范围。调用密钥权限范围之外的端点会返回 403 MISSING_SCOPE。现有密钥的权限范围无法编辑：请创建一个具有所需权限范围的新密钥。 每个端点页面也会在 Authorization 字段正下方注明其所需的权限范围。
有些权限范围的影响超出其名称所示。files:write 和 apps:deploy 会在应用中运行你选择的代码，snapshots:read 会下载整个应用及其环境变量，envs:read 会暴露应用的所有密钥，databases:credentials 会提供数据库密码，而通过 workspaces:manage 授予的访问权限在密钥被吊销后仍然有效。请只给每个集成授予它所需的权限范围。

​
将密钥限定到特定资源

密钥还可以限定为最多 30 个应用和数据库。针对其他任何资源的调用，或无法缩小到这些资源的账户级端点调用，都会返回 403 RESOURCE_NOT_ALLOWED。账户信息等列表端点只返回密钥涵盖的资源。 受限密钥不能带有 blob:read 或 blob:write 权限范围，因为存储的文件属于账户，而不属于某个应用。请为应用创建一个密钥，再为 Blob Storage 另建一个。

​
错误

其他所有代码见错误代码。

​
无效密钥防护

为保护所有账户，API 会暂时封锁持续发送不属于任何账户的 API 密钥的 IP 地址，在短时间内返回 429 RATE_LIMITED。正常使用的有效密钥不受影响。如果请求收到 401，不要循环重试：请修正或更换密钥。

​
后续步骤

你的第一个请求

基础 URL、第一个 curl 调用和响应格式。

限制与约束

各套餐的请求额度和受限地区。