跳到主要内容

身份认证

本节记录的每个端点，除 GET /v1/health 之外都需要 bearer 令牌：

Authorization: Bearer <token>

两种凭据​

同一个请求头接受两种凭据类型，但它们能触及的范围并不一样。

会话令牌API 密钥
形式你登录控制台时签发的 JWTshk_ 后跟 48 个十六进制字符
来源浏览器会话，自动刷新在控制台的 API 密钥页面创建一次
有效期短期有效；会过期并刷新直到你吊销它
行事所用的角色你在组织里的真实角色，admin 或 member始终是 member
组织你选中的那一个只有密钥创建时所在的组织
账户端点（/v1/me、/v1/ssh-keys）允许拒绝，返回 401 TOKEN_INVALID
管理员操作，包括计费你是管理员时允许拒绝，返回 403 ADMIN_REQUIRED

凡是无人值守运行的东西，都用 API 密钥。会话令牌会过期，所以带着它的脚本会毫无预警地失效。创建和吊销的方法见 API 密钥。

curl -s "$SUPERHEAT_API/v1/instances" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

选择组织​

实例、模板、余额和密钥都属于某个组织。X-Org-Id 头决定一个请求作用于哪一个：

请求头会话令牌API 密钥
未设置你的个人组织密钥自己的组织
设为你所属的某个组织该组织，使用你在其中的角色仅当与密钥的组织一致时才允许
设为你不属于的组织403 NOT_A_MEMBER403 ORG_MISMATCH
不是合法的 id400 INVALID_ORG_ID403 ORG_MISMATCH——密钥会先拿这个头和自己的组织 id 比对，再去校验它是否合法
curl -s "$SUPERHEAT_API/v1/instances" \
  -H "Authorization: Bearer $SUPERHEAT_KEY" \
  -H "X-Org-Id: 9c1b7d4e-3a52-4a1f-8c6d-b0e9f2a71c48"

用 GET /v1/orgs 列出你可以操作的组织，它会返回每个组织的 id、name、personal 标记、你的 role 以及余额。这个调用需要会话令牌。

失败情形​

状态码代码含义
401TOKEN_INVALID缺少请求头、令牌格式错误、API 密钥未知或已吊销，或者把 API 密钥发到了账户端点
401TOKEN_EXPIRED会话令牌已过期——重新登录
403NOT_A_MEMBERX-Org-Id 指定的组织不是你的
403ORG_MISMATCHAPI 密钥所属的组织与 X-Org-Id 不是同一个
403ADMIN_REQUIRED该操作仅限管理员，或者你用 API 密钥去做了它
400INVALID_ORG_ID在会话令牌的请求中，X-Org-Id 不是一个合法的 id

完整的响应结构见错误。

把密钥当密码对待

任何拿到 shk_ 密钥的人，都能部署实例、花掉你组织的余额。不要把密钥放进代码仓库；凡是粘贴到你无法控制的地方的密钥，一律吊销。