Screenshare认证与权限
API Key
公开 API 使用请求头认证：
Authorization: Bearer uss_live_<64位随机十六进制字符>
不要把密钥放在查询参数、请求正文或 URL 中。浏览器登录 Cookie 不能替代 API Key，API 也不会给第三方创建网站登录会话。只使用 HTTPS 原始地址，客户端不要跟随重定向后继续转发密钥。
GET /v1/health 不需要密钥。其他 v1 接口都需要有效密钥。GET /v1/me 不要求额外业务权限，可用于确认当前凭证。
权限矩阵
| Scope | 可调用的能力 | 个人密钥 | 组织密钥 |
|---|---|---|---|
public:read |
精确 USS 记录查询 | 是 | 是 |
entitlements:read |
密钥所属个人或组织的权益 | 个人权益接口 | 绑定组织权益接口 |
records:read |
组织记录列表、筛选和详情 | 否 | 是 |
invitations:read |
组织邀请列表和状态 | 否 | 是 |
invitations:write |
新建、取回完整链接、撤销未使用邀请 | 否 | 是 |
tickets:read |
已加入工单的列表和进度 | 否 | 是 |
读写权限互不隐含。只有 invitations:write 的密钥可以新建邀请，但不能调用邀请列表；需要两种能力时应同时选择两个 scope。取回完整邀请链接属于写权限范围，因为该链接本身是可分发的加入凭证。
谁可以创建
- 所有有效账号都可以创建个人密钥。
- 组织密钥和 Webhook 需要账号是对应有效组织的
manager成员。 - 普通组织成员不能创建组织 API 凭证；他们原有的网页邀请和工单操作权限保持不变。
- 全局 Admin 或 SSer 必须同时是该组织的实际管理员成员，才能通过此开发者平台获取组织凭证。
- 凭证由创建者在自己的个人中心管理；其他账号不能查看其完整密钥或撤销接口中的凭证。
实时失效与永久撤销
个人和组织密钥均可选择 1–365 天有效期或“永久有效”，默认仍为 90 天。在已登录的个人中心生成 API Key 无需再次验证账户密码或两步验证码；创建 Webhook 的验证流程见 Webhook 接入。
GET /v1/me 的 expires_at 是 ISO 8601 时间或 null。null 仅表示密钥没有自动到期时间，客户端不要将其转换为日期、显示为已过期或据此跳过错误处理。网站密钥列表也显示“永久有效”。有期限的现有密钥保持原到期时间；需要永久密钥时，请创建新密钥并按下方步骤轮换。
服务器每次请求检查密钥有效期（若设置）、撤销状态、账号状态以及当前组织管理员身份。以下变更会永久撤销相关密钥（包括永久密钥），并停用相应 Webhook：
| 变更 | 影响 |
|---|---|
| 从组织移除或从管理员降为普通成员 | 该账号绑定该组织的密钥及回调 |
| 组织归档 | 绑定该组织的密钥及回调 |
| 账号停用 | 该账号的全部密钥及回调 |
| 修改或重置密码 | 该账号的全部密钥及回调 |
恢复组织、重新加入或重新启用账号不会恢复旧凭证。请重新创建并部署。普通网页退出登录不会撤销长期 API Key。
轮换
- 创建相同组织、相同或更小权限的新密钥。
- 调用
/v1/me验证新凭证。 - 更新应用的服务端配置，并确认正常调用。
- 撤销旧密钥。
邀请幂等记录以密钥为作用域。在恢复一个结果不确定的创建请求时，先用原密钥完成恢复；不要立即换新密钥并重复创建。
每个账号最多保留 20 把尚未到期且未撤销的密钥，永久密钥同样计入。永久密钥与有期限密钥使用相同的权限、组织边界、调用限额和审计规则。密钥仅保存不可逆摘要，完整值不会再次提供。
API Key 有效期与邀请链接、服务权益的有效期互相独立。永久密钥不会产生永久邀请、免费次数或无限调用额度。