免登与鉴权

组织应用有两层凭证，分别解决"你的后端是谁"和"当前是哪个用户在用"。

时序图

┌─────────┐ 1.点「打开」    ┌──────────┐ 2.POST /api/orgs/{org}/apps/{app}/auth-code
│ 客户端   │ ─────────────→ │ 应用窗口壳 │ ────────────────────────→ 机灵兔服务端
│ 主窗口   │                │(机灵兔的代码)│ ←──────── {auth_code}
└─────────┘                └────┬─────┘
                                │ 3. iframe.src = 你的页面URL?jlt_auth_code=..&jlt_org_id=..&jlt_app_id=..
                           ┌────▼─────┐ 4. 页面把 auth_code 发给自己的后端
                           │ 你的页面   │
                           └────┬─────┘
                           ┌────▼─────┐ 5. POST /api/open/auth/token  (app_key+app_secret)
                           │ 你的后端   │ 6. POST /api/open/auth/user  (auth_code)
                           └──────────┘    ← {user_id, nickname, avatar_url, org_id, org_role, team_ids}

两层凭证

凭证	谁持有	换取方式	有效期	用途
app_key / app_secret	你的后端（长期保存）	应用创建时颁发，可轮换	长期	换 app access token
app access token	你的后端	POST /api/open/auth/token	2 小时	调用其余开放 API
一次性授权码（authCode）	你的页面 → 你的后端	客户端打开应用时拼在 URL 上；也可用 JSAPI requestAuthCode() 重新获取	5 分钟、只能用一次	换用户身份

app_secret 只能放在服务器

app_secret 一旦泄露到页面/客户端代码，任何人都能拿它换 app access token 调用你被授予的所有能力（包括代表你的应用发消息、消耗你组织的 AI 额度）。 如果怀疑泄露，立即在应用设置里「轮换密钥」，旧密钥会即时失效。

换 app access token

POST /api/open/auth/token
Content-Type: application/json

{ "app_key": "oak_xxx", "app_secret": "xxx" }

{ "access_token": "xxx", "token_type": "Bearer", "expires_in": 7200 }

token 有效期 2 小时，请缓存并在过期前刷新（例如提前 1 分钟），不要每次 请求都重新换取——同一个 app_key 的换取频率限制是 20 次/分钟。

换用户身份

POST /api/open/auth/user
Authorization: Bearer <app access token>
Content-Type: application/json

{ "auth_code": "..." }

返回：

{
  "user_id": "u_123",
  "nickname": "张三",
  "avatar_url": "https://...",
  "org_id": "org_abc",
  "org_role": "member",
  "team_ids": ["team_1", "team_2"]
}

拿到这个身份后，请在你自己的应用里建立会话（cookie/session 等，跟机灵兔的 登录态完全独立）。org_id/org_role 是打开应用当下所在的组织上下文—— 自建应用固定是应用所属组织；被其他组织安装的应用，这里是安装方组织。

authCode 是一次性的：换过一次、或超过 5 分钟，就返回 400，让页面用 jlt.requestAuthCode() 重新取一枚新码再试。用完建议顺手把 URL 上的 jlt_auth_code 参数清掉（history.replaceState），避免用户刷新页面时拿旧码 重试。

常见错误

HTTP 状态	含义
400	authCode 无效 / 已使用过 / 已过期（取新码重试）
401	app token 缺失/无效/过期；app_key/app_secret 不正确；密钥已被轮换；应用已停用或组织已解散
402	调用 AI 能力时，应用所属组织尚未开通钱包
403	这项能力没有被授予（错误信息会提示找谁开）
429	触发了限流，稍后重试

更多错误场景与排查步骤见 FAQ 与故障排查；secret 的存放与 轮换纪律见安全最佳实践。