Auth API

Auth API 是通过社交登录对 ServiceUser（某个 Space 所运营产品的普通注册用户）进行身份验证的 OAuth 流程。使用关联到 ServiceLogin 配置的提供方（例如 Google）登录后，该 API 会签发 accessToken 和 refreshToken。签发的 accessToken 是仅用于调用 ACMA、ACDA 的 Bearer 令牌，不能用于 CMA、CDA。不存在跨身份边界的令牌。

基础 URL 为 https://auth.weegloo.com/v1，所有路径都位于 /spaces/{spaceId}/... 之下。所有请求和响应正文均为 JSON。如果是浏览器应用，建议使用官方 SDK weegloo-service-user，而不是直接处理这些 HTTP 请求和响应。本页讲解的是该 SDK 在内部调用的 HTTP 请求和响应格式。在无法使用 SDK 的环境（服务器、原生应用、脚本）中自行实现该流程时，可参考本页。

登录流程

以下是基于网页浏览器应用的登录流程。原生应用（Android、iOS）的回调处理有所不同，将在原生应用回调中单独介绍。

登录分四个步骤进行。

  1. 将浏览器导航到登录入口 URL（/spaces/{spaceId}/login/oauth2/{provider}）。该 URL 会启动通往提供方（Google）登录页面的重定向链。
  2. 登录完成后，Weegloo 会将浏览器返回到 ServiceLogin 中配置的 callbackUrl，并在地址后附加 ?exchangeToken=<一次性令牌>。
  3. 回调页面从地址中读取 exchangeToken，发送到令牌交换端点（POST /spaces/{spaceId}/oauth/token），并在响应中接收 accessToken 和 refreshToken。
  4. 之后将 accessToken 作为 Bearer 令牌调用 ACMA、ACDA。在过期（expiresAt）之前使用 refreshToken 进行刷新，登出时废弃令牌。

exchangeToken 是一次性的。处理完回调后应立即从地址栏中将其移除，以防泄露和重复使用（使用 SDK 时会自动处理）。

原生应用回调：深度链接桥接

Android、iOS 原生应用同样通过相同的 OAuth 流程登录。只是 callbackUrl 中只能填写网页地址，因此连接方式有所不同。

文档中支持的 callbackUrl 是 https://... 这样的网页地址。像 myapp:// 这类由应用注册的自定义 URL scheme 会被拒绝，因此不能直接用作回调地址。所以原生应用会把 callbackUrl 设为部署在 Web Hosting 上的 https 桥接页面，由该页面把回调中携带的 ?exchangeToken=... 转交给应用的深度链接（例如 myapp://auth/callback?exchangeToken=...）。应用再用该 exchangeToken 自行完成令牌交换（上面登录流程的第 3 步，POST /spaces/{spaceId}/oauth/token）。

  • 深度链接只传递一次性的 exchangeToken。accessToken、refreshToken 由应用自行交换获取，不会经过深度链接。桥接页面在传递该值之后，也会从地址中移除 exchangeToken（与登录流程中的回调同样的原则）。
  • 尽量使用经过验证的深度链接（Android App Links、iOS Universal Links）。未经验证的自定义 scheme 可能会被设备上安装的其他应用拦截。
  • 提供方（例如 Google）的 OAuth 客户端即使面向原生应用，也要创建为 Web application 类型。因为 OAuth 重定向指向的不是应用，而是 auth.weegloo.com（网页地址）。

部署桥接页面的方法在 Web Hosting 中介绍。

令牌模型

令牌交换和刷新返回相同形态的令牌响应。响应中包含的令牌字符串和时间为下方示例值，实际上是不透明的机密字符串（由于流程要经过提供方登录，无法原样照搬真实值）。

{
  "accessToken": "QY3xK9pR2mLs7Vc0Zt8Nf4Wd1Bj6Hg5Ua2Ee9Ck3PoZt8Nf4Wd",
  "tokenType": "Bearer",
  "scope": ["APP"],
  "createdAt": "2026-06-18T05:00:00.000Z",
  "expiresAt": "2026-06-19T05:00:00.000Z",
  "refreshToken": "Rf7Hn2Qw9Zx4Tp1Lk6Vc3Bm8Yd5Gs0Ae2Uj7Co4NeLk6Vc3Bm",
  "refreshExpiresAt": "2026-06-21T05:00:00.000Z"
}
字段类型说明
accessTokenstring用于调用 ACMA、ACDA 的 Bearer 令牌。
tokenTypestring令牌种类。始终为 "Bearer"。
scopestring 数组令牌的权限范围。ServiceUser 令牌为 ["APP"]。
createdAtstring (date-time)令牌签发时间。
expiresAtstring (date-time)accessToken 的过期时间。
refreshTokenstring刷新 accessToken 时使用的令牌。
refreshExpiresAtstring (date-time)refreshToken 的过期时间。以 createdAt 为基准的 3 天后。

三种令牌的生命周期如下。

  • exchangeToken 是一次性的，生命周期很短。回调后须立即交换。它不包含在交换响应中，而是在登录流程的第 2 步通过地址传递。
  • accessToken 的生命周期不是固定值。确切的过期时间包含在响应的 expiresAt 中，请以该值为准判断。仅用于 ACMA、ACDA。
  • refreshToken 自签发起 3 天内有效（refreshExpiresAt）。调用刷新后会签发新的 accessToken 和 refreshToken 对，先前的一对则被废弃（轮换，rotation）。每次刷新后，上一个 refreshToken 都将无法再使用。

API

下面四个端点的基础 URL 均为 https://auth.weegloo.com/v1。按登录入口（GET）、令牌交换（POST）、令牌刷新（POST）、登出（DELETE）的顺序讲解。