Auth API

最后更新：2026年7月3日

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，而不是直接处理这些底层接口。本页讲解的是该 SDK 在内部调用的 HTTP 底层接口。在无法使用 SDK 的环境（服务器、原生应用、脚本）中自行实现该流程时，可参考本页。

登录流程

登录分四个步骤进行。

  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 时会自动处理）。

令牌模型

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

{
  "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）的顺序讲解。