跳到主要内容

免登流程

端内免登由客户端 SDK 获取一次性 code，再由应用后端换取当前用户身份。SDK 内部完成客户端授权码申请，应用页面无需直接调用客户端授权接口。

接入前配置​

在管理后台「内部应用」中完成以下配置：

  1. 应用已启用并发布版本，且已开启客户端显示。
  2. 已配置当前端（PC 或移动端）的应用入口。
  3. 已将实际应用页面配置到「端内免登地址」白名单。
  4. 当前用户在应用可见范围内。

调用流程​

应用页面
   │ 1. SDK 调用 requestWorkbenchAuthCode() 获取一次性 code
   │ 2. 通过 HTTPS 将 code 提交给应用后端
   ▼
应用后端
   │ 3. POST /auth/v1/oauth/token 获取 access_token
   │ 4. POST /auth/v1/oauth/userinfo?access_token=... 提交 code
   ▼
应用后端获得 {userId, nickName, avatar}，创建业务系统自己的登录态

前端调用示例​

<script src="/assets/sdk/twt-link-universal.umd.min.js"></script>
<script>
  async function loginFromWorkbench() {
    const sdk = window.__TWT_LINK__;
    if (!sdk || !sdk.isTwtLinkPlateform()) {
      window.location.href = "/login";
      return;
    }

    const { code } = await sdk.requestWorkbenchAuthCode();
    const response = await fetch("/api/workbench/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ code }),
    });

    if (!response.ok) {
      throw new Error("登录失败，请重新申请授权码");
    }
  }

  loginFromWorkbench();
</script>

前端只负责获取并提交 code，不保存 client_secret、access_token 或用户身份信息。

服务端调用示例​

1. 获取应用令牌​

应用后端使用服务端保存的 client_id 和 client_secret 调用 Token 接口：

POST /auth/v1/oauth/token
Content-Type: application/json

{
  "client_id": "应用 ID",
  "client_secret": "应用密钥",
  "grant_type": "client_credentials"
}

成功响应示例：

{
  "access_token": "应用级令牌",
  "expires_in": 7200
}

2. 获取当前用户信息​

使用 Token 接口返回的 access_token 和前端提交的一次性 code 调用 UserInfo 接口：

POST /auth/v1/oauth/userinfo?access_token=<access_token>
Content-Type: application/x-www-form-urlencoded

code=<code>

成功响应示例：

{
  "userId": "10001",
  "nickName": "张三",
  "avatar": "https://cdn.example.com/avatar/10001.png"
}

code 只能使用一次，兑换成功后立即失效。client_secret 和 access_token 只能由应用后端保存和使用，不能下发到前端。

常见错误​

HTTP 状态码错误码处理建议
400INVALID_REQUEST检查 access_token、code 和请求格式
400INVALID_GRANTcode 已过期、已使用或与应用不匹配；重新获取 code
401INVALID_TOKEN重新获取应用 access_token
403USER_NOT_VISIBLE检查用户是否在应用可见范围内
500SERVER_ERROR稍后重试