Side Space

开始

认证

带权限范围的个人访问令牌、作为独立成员的 AI agent，以及代表用户操作的应用所用的 OAuth。

查看 Markdown

每个 /v1 调用都带一个 Bearer 令牌：

HTTP
GET /v1/spaces HTTP/1.1
Host: side.example.com
Authorization: Bearer ssp_6Jw…

按程序代表谁操作，有三种拿令牌的方式。

程序令牌怎么拿
你的脚本、CI 任务或服务个人访问令牌 ssp_…sidespace token create
应该以自己身份出现的 AI agent 或机器人AI 成员的令牌sidespace agent create，再 token create --agent
给别人登录使用的应用OAuth 2.1 访问令牌授权码流程加 PKCE

人在应用里用邮箱验证码登录；组织设置了单点登录时，用组织的身份提供方登录。验证码只能用一次。同一个邮箱或同一个网络尝试太多时，登录接口返回 429，代码 rate_limited，并带 Retry-After 头（秒）；一小时内输错 10 次验证码，这个邮箱在这一小时剩下的时间里都会被锁定。

个人访问令牌

令牌以 ssp_ 开头。服务器只保存它的哈希，所以只在生成时显示一次。每个令牌都有权限范围（scope），可以限定只用于某几个空间，默认 90 天后过期（--expires-days 0 表示永不过期）。

Shell
sidespace token create "nightly export" --scope files:read --space "Film A"
sidespace token list
sidespace token revoke tok_01JD…

CLI 也可以直接用令牌，不需要登录：设置 SIDESPACE_TOKEN=ssp_…，或者加 --token 参数。

权限范围

权限允许做什么
files:read列空间、浏览、搜索、读版本和附加信息、下载、看通知
files:write在 files:read 之外，还能上传、新建、改名、移动、删除、恢复
sidecars:write写任何命名空间的附加信息
sidecars:write:<ns>只写这一个命名空间；以 * 结尾时包括它下面一组，例如 sidecars:write:x-acme.*
renditions:write上传缩略图、代理等派生文件
events:read读变更日志和实时信号
shares:manage新建、吊销分享链接
members:manage添加、修改、移除成员
webhooks:manage管理空间的 Webhook（令牌的主人还需要是空间管理员）
runs:write运行转写、AI 标签、转格式等动作（编辑者以上）
pipelines:manage管理流水线（空间管理员）
plugins:manage安装、更新、停用、卸载插件（空间管理员）
comments:write发表、回复、解决评论（评论者以上）
admin以上全部，另外还能新建、改名空间

权限范围不会超出令牌主人在空间里的角色：一个查看者生成的 admin 令牌，在那个空间里仍然只是查看者。

令牌做不了这几件事：管理设备、令牌和 AI 成员。它们只能在已登录的应用或 CLI 里做，所以令牌没法给自己生成一个权限更大的令牌。

会遇到的错误

  • 403，返回 {"error": {"code": "forbidden", "message": "this token needs the files:write scope"}}，写明缺哪个权限。
  • 404：访问令牌范围以外的空间时返回，和空间不存在时一模一样。API 不会透露你看不到的空间是否存在。
  • 402，代码 quota_exceeded：套餐限额挡住了一次保存、一次加成员或一次 AI 任务。消息里写明是哪项限额、算在谁的套餐上（空间算在所有者头上），按月的额度何时重置，原样显示即可。GET /v1/me/plan（或 sidespace plan）返回你自己的套餐、限额和用量。

AI 成员

AI agent 或服务账号可以作为独立成员加入空间，而不是借用某个人的身份。它的每一次改动都记为 actor_kind: "agent"，应用里的成员列表、版本记录和动态会显示紫色的 Agent 标记。

Shell
sidespace agent create "Clip Tagger"
sidespace members "Film A" --add "Clip Tagger" --role editor
sidespace token create tagger --agent "Clip Tagger" \
  --scope files:read --scope "sidecars:write:x-tagger.*"
sidespace agent rm "Clip Tagger"   # 吊销它的所有令牌，并把它移出所有空间

AI 成员不能用邮箱验证码登录，只能用令牌。移除后，它以前的改动仍然保留它的名字。

服务器自己的处理也会标明来源。比如媒体处理生成的缩略图，记为 actor_kind: "plugin"、actor_via: "media"。

应用接入（OAuth）

代表别人操作的应用（网页应用、桌面工具、MCP 客户端）用 OAuth 2.1 授权码流程加 PKCE，不需要让用户复制令牌。服务器元数据在 /.well-known/oauth-authorization-server。

注册应用：

Shell
sidespace app create "Acme Review" --redirect https://acme.example/oauth/callback
# client_id = app_01…
sidespace app create "Acme Sync" --redirect https://acme.example/cb --confidential   # 服务端应用，另给 client_secret
sidespace app list
sidespace app rm app_01…      # 删除后所有授权立即失效

然后：

  1. 把用户带到 /oauth/authorize，带上 response_type=code、client_id、redirect_uri、state、code_challenge、code_challenge_method=S256 和 scope（空格分隔，例如 files:read files:write）。
  2. 用户用邮箱验证码登录，勾选给哪些权限、哪些空间，然后回到 redirect_uri?code=…&state=…&iss=…。
  3. 应用以表单 POST /oauth/token：grant_type=authorization_code、code、redirect_uri、client_id、code_verifier。返回 access_token（ssp_…，1 小时）和 refresh_token（ssr_…，90 天，每次续期都换新）。
  4. 续期用 grant_type=refresh_token；退出时 POST /oauth/revoke。
Shell
curl -X POST https://side.example.com/oauth/token \
  -d grant_type=authorization_code -d code="$CODE" -d client_id=app_01… \
  -d redirect_uri=https://acme.example/oauth/callback -d code_verifier="$VERIFIER"
  • 不传 scope 时默认 files:read files:write comments:write runs:write。admin 不能授予应用，用户也可以去掉某些权限、只给某几个空间。
  • 授权就是一个令牌：在用户的 sidespace token list 里显示为 app:…，可以单独吊销。权限、空间范围和 403/404 的规则与普通令牌完全一样。
  • 回调地址必须是 https、本机的 http（端口任意，RFC 8252），或者应用自己的 scheme（cursor://…）。公开客户端必须用 PKCE。
  • 应用也可以自行注册（POST /oauth/register，RFC 7591，只能是公开客户端），MCP 客户端就是这样接入的。同意页会提示这是自行注册的应用。