认证

拿到 bearer token、保持有效，并选对凭据种类。

curl -X POST https://starforge.your-company.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "..."}'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "username": "alice", "role": "user" }
}

之后每个请求都带上 Authorization: Bearer <token>。

​

四种凭据

它们不能互换，用错种类是最常见的对接问题。

Access token · JWT，8 小时

POST /api/auth/login 和 CLI 设备流返回的东西，代表一个人。里面带角色，所以管理员的 token 能打开管理接口。你写脚本代表自己操作时用的就是它。

Refresh token · 30 天

和 access token 一起签发，但只通过 httpOnly Cookie 下发，不进响应体——浏览器里的 JavaScript 读不到它。POST /api/auth/refresh 用它换新的 access token。命令行客户端不用它，改走设备流。

Ingest token · 30 天，绑定单次运行

以 STARFORGE_TOKEN 注入训练容器，只对一次 run 有效，也只有 /api/ingest/* 认它。作业手里只有这个， 永远拿不到你的账号凭据。见从训练代码回传。

Deployment token · 可吊销，不过期

只授权访问某一个模型部署，别的都不行。它独立于任何登录会话， 所以创建它的人离职后服务照常运行。在控制台吊销。

角色只有 admin 和 operator（控制台上把后者显示为「Member」）。operator 的 token 打管理接口返回 403，不是 401——后者会让人误以为 token 有问题。

​

从浏览器或脚本登录

SF_TOKEN=$(curl -sX POST https://starforge.your-company.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "'"$SF_PASSWORD"'"}' | jq -r .token)

每个 IP 每分钟 10 次。启用了 OIDC 的部署会关掉这条路由，先用 GET /api/auth/config 看看这套部署 支持哪些登录方式，别想当然。

​

从没有浏览器的机器登录

设备流，RFC 8628。sf login --device-flow 走的就是这条路，SSH 会话和构建机上应该用它。

1. 申请验证码

   curl -sX POST https://starforge.your-company.com/api/cli/device/code \
     -H "Content-Type: application/json" -d '{}'
   

   {
     "device_code": "5f3a...",
     "user_code": "WDJB-MJHT",
     "verification_uri": "https://starforge.your-company.com/cli/device",
     "verification_uri_complete": "https://starforge.your-company.com/cli/device?user_code=WDJB-MJHT"
   }
   
2. 在浏览器里批准

   在任何一台已登录的设备上打开 verification_uri_complete。

3. 轮询直到批准

   curl -sX POST https://starforge.your-company.com/api/cli/device/token \
     -H "Content-Type: application/json" \
     -d '{"device_code": "5f3a..."}'
   

   未批准时返回 authorization_pending，批准后返回 access token 和 expires_in。 轮询间隔不要低于 5 秒，上限是每分钟 20 次。

​

确认成功

curl -H "Authorization: Bearer $SF_TOKEN" \
  https://starforge.your-company.com/api/auth/me

返回用户名、角色和配额。这里拿到 401，说明 token 没带、格式不对或已过期——先重新登录，再去查别的。

​

过期怎么办

access token 默认 8 小时（部署侧 FORGE_JWT_HOURS 控制）。过期后接口返回 401。按你的身份分两种恢复方式：

• 浏览器会话：带 refresh Cookie 调 POST /api/auth/refresh。
• 脚本或 CI：重新登录，或重跑设备流。不要跨次运行缓存 token 然后赌它还能用； 先看 GET /api/auth/me，遇到 401 就重新认证。

POST /api/auth/logout 会吊销 refresh token；部署配了 Redis 时，access token 也会立即失效， 而不是等到自然过期。

为什么 refresh token 从不出现在响应体里

JavaScript 能读到的 token，注入的脚本也能偷走，而 30 天的 refresh token 比 8 小时的 access token 值钱得多。放进 httpOnly Cookie，意味着一个 XSS 漏洞的代价是一次会话，而不是一个月的访问权。 这同时也意味着命令行客户端根本用不了它——设备流因此是一条独立设计的路径，而不是补丁。