Skip to content
Subaya

认证与 API 密钥

Subaya 针对同一个 API 支持两种认证模式。

API 密钥——SUBAYA_API_KEY（agent 与 CI）

Section titled “API 密钥——SUBAYA_API_KEY（agent 与 CI）”

最简单的路径，也是用于 AI agent 和 CI 流水线的方式。设置环境变量后，每个 suya 命令 （以及平台 API）都会读取它：

Terminal window
export SUBAYA_API_KEY="sk_live_..."
suya auth whoami      # confirm the identity the key resolves to

无需浏览器、无交互步骤——非常适合无头环境。在控制台的 Settings → API keys 下签发和管理密钥。

密钥按环境区分

Section titled “密钥按环境区分”

前缀会告诉你一个密钥属于哪个环境，而密钥只对该环境有效：

  • sk_live_… — 生产 API（https://subaya-dev.com）。
  • sk_test_… — 保留给非生产环境。

如果把密钥出示给错误的主机，suya auth whoami 会以 wrong_environment（而不是笼统的 “无效密钥”）拒绝它，并告诉你该到哪里签发正确的密钥。完整的原因列表参见 CLI: auth。

OAuth 浏览器登录（人类）

Section titled “OAuth 浏览器登录（人类）”

用于工作站上的交互式使用：

Terminal window
suya auth login                 # opens a browser (loopback redirect)
suya auth login --no-browser    # print a code to approve from any device

suya auth login 会打开浏览器并重定向回 127.0.0.1，因此它要求浏览器位于同一台机器上。 当情况并非如此时——SSH、容器、远程开发机——请使用 --no-browser：CLI 会打印一个短代码， 你在任意设备的浏览器中批准它，CLI 随即取得令牌。如果浏览器无法打开，或者重定向始终没有到达， CLI 也会自行切换到该流程。参见设备流程演练。

CLI 会在本地（~/.config/suya/ 下）存储所得到的令牌。检查或清除它：

Terminal window
suya auth status    # local status, without calling the server
suya auth logout    # log out and revoke the local token

优先级

Section titled “优先级”

当存在多于一个凭据时，suya 按以下顺序解析：

  1. --token 全局标志
  2. SUBAYA_API_KEY
  3. 本地存储的 OAuth 令牌（~/.config/suya/auth.json）

指向不同的主机

Section titled “指向不同的主机”

如果你需要面向非默认的 API 端点，所有命令都接受 --host（默认 https://subaya-dev.com）。

后续步骤

Section titled “后续步骤”