公开接口

Passport 提供了一套完整的 REST API，供开发者在任意语言或框架的应用中调用，实现认证鉴权功能。

本文档以 passport-service 的路由注册（internal/router/router.go）为基准编写，所有接口路径、参数与响应结构均取自当前实现。

Base URL

根据部署环境选择：

# 生产环境
https://passport.vancone.com

# 测试环境（仅限内网访问）
http://passport.beta.vancone.com

所有接口统一前缀为 /api/passport/service/v1。

请求说明

认证方式

Token 通过以下两种方式之一传递，服务端优先读取 Cookie：

登录成功后，服务端会同时下发两个 Cookie：passport_token（Token）与 passport_username（用户名或登录名）。

需要认证的接口

服务端按 passport.filter.url-patterns 配置对匹配的路由做 Token 校验，未匹配的路径不做校验。默认需要携带 Token 的接口为：

显式的免校验规则（代码硬编码，不受配置影响）：

• POST /api/passport/service/v1/account（账号注册）
• /api/passport/service/v1/account/enterprise-activation/*（企业账号激活流程）
• /api/passport/service/v1/account/forgot-password/*（找回密码全流程）

请求体格式

除「验证滑块验证码」接口使用 application/x-www-form-urlencoded 外，其余接口请求与响应均为 JSON 格式。

响应格式

所有响应遵循统一格式：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

HTTP 状态码与业务状态码是两套独立的东西，请务必区分：

API 列表

Login 模块

1.1 用户登录

GET  /api/passport/service/v1/login
POST /api/passport/service/v1/login

滑块验证码为条件校验：账号上次登录成功（或首次登录）时不校验验证码，captchaToken 可为空；账密输错一次后再次登录必须携带验证码票据，否则返回 10007 Captcha verification required after a failed attempt。携带了票据但校验未通过返回 10005。接入方建议：本地记录失败状态，失败后下一次提交前先过滑块（见 8.2、8.3）。

请求参数（GET 走 query，POST 走 JSON body）：

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "username": "admin"
  }
}

响应中只有 token 与 username 两个字段。username 取账号的 name，未设置 name 时回退为 userId。

业务结果：登录成功时同时下发 passport_token 与 passport_username 两个 Cookie，有效期由服务端配置 passport.cookie.expired-seconds 决定（默认 86400 秒）。

锁定策略：连续登录失败次数超过服务端配置 passport.login-failure-times-limit（默认 5）后，账号被锁定，返回 10003；登录成功后失败计数清零。

失败响应（HTTP 200）：

{
  "code": 10002,
  "message": "Incorrect password"
}

1.2 登出

DELETE /api/passport/service/v1/login

响应：

{
  "code": 0,
  "message": "success"
}

说明：清除 passport_token 与 passport_username 两个 Cookie。服务端为无状态 JWT，不维护会话黑名单，登出仅清除客户端 Cookie。

App 登出：请求体可携带 { "refreshToken": "..." }，服务端会删除对应的 refresh token 记录实现服务端吊销；Web 端不带请求体，行为不变。

1.3 App 登录(桌面 / 移动端)

POST /api/passport/service/v1/login/app

供原生 App(Electron 桌面端、Android)使用的独立登录端点。与 Web 登录(1.1)的区别:

• 不种 Cookie,Token 由客户端自行安全存储;
• 响应额外返回 refreshToken(有效期 30 天),用于静默续期(见 2.5);
• 登录历史中的 clientType 记录客户端类型。

请求体:

响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "username": "admin",
    "refreshToken": "kN9xQ2p...43位URL安全随机串"
  }
}

失败语义与 1.1 完全一致(HTTP 200 + 业务码 10001~10005)。

设计说明:App 登录与 Web 登录是两个独立端点(逻辑同一套,契约分开)——Token 生命周期、安全策略、后续废弃节奏(迁移 OIDC PKCE)都按客户端独立演进。

1.4 扫码登录

扫码登录（Web 展示二维码 + 扫码设备确认）包含创建会话、轮询状态、上报扫码、确认登录四个接口，已独立成文，见「扫码登录接入」。

Token 模块

2.1 生成签名

应用账号换取 Token 的第一步。

POST /api/passport/service/v1/token/signature

请求体：

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "signature": "ABCDEF123456...",
    "timestamp": "1640000000000"
  }
}

签名计算方式（服务端实现，客户端调用本接口即可，无需自行计算）：

timestamp = 当前毫秒时间戳
signature = UPPER(HEX(HMAC-SHA256(secretAccessKey, accessKeyId + timestamp)))

2.2 生成 Token

POST /api/passport/service/v1/token

请求体：

响应：data 为 Token 字符串（不是对象）。

{
  "code": 0,
  "message": "success",
  "data": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
}

签名校验失败时返回 HTTP 500、code 为 -1，message 为 signature validation failed。

2.3 验证 Token

POST /api/passport/service/v1/token/validate

请求体：

响应：data 为 布尔值。

{
  "code": 0,
  "message": "success",
  "data": true
}

2.4 获取 Token 剩余有效期

POST /api/passport/service/v1/token/expiration

请求体：

响应：data 为剩余秒数（整数）。

{
  "code": 0,
  "message": "success",
  "data": 86399
}

说明：Token 无效或已过期时返回 0。Token 有效期固定为签发后 24 小时，不支持续期，过期后需重新登录或重新申请。

2.5 刷新 Token(App)

POST /api/passport/service/v1/token/refresh

使用 1.3 返回的 refreshToken 换取新的 access token 与新的 refresh token。旋转式:旧 refreshToken 在本次调用中被消费,立即作废。

请求体:

响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "新的refreshToken"
  }
}

说明:

• 新 access token 按服务端存储的账号重新签发,权限变更在刷新后即时生效;
• refreshToken 无效或已过期返回 HTTP 401 / code 11002,客户端应回到登录页;
• 该接口免滑块:refreshToken 本身即凭证;
• 登出时携带 refreshToken 调用 DELETE /login 可在服务端吊销(见 1.2)。

Token 结构

Token 为 ES256 签名的 JWT，Claims 如下：

Account 模块

3.1 查询当前账号信息

GET /api/passport/service/v1/account

需要携带 Token。返回的是 Token 中 acid 对应的账号。

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "1234567890",
    "userId": "user123",
    "type": "PERSONAL",
    "name": "张三",
    "email": "user@example.com",
    "phone": "13800138000",
    "tenantId": "0",
    "applicationId": ""
  }
}

字段说明：

• 出于安全考虑，响应中不包含 password 字段。
• lastLoginTime、birthDay、applicationName 为派生字段，当前实现不会填充，响应中不会出现。生日信息请通过「用户资料」接口获取（见 4.1，字段名为 birthday）。

3.2 创建账号（注册）

POST /api/passport/service/v1/account

该接口免 Token 校验。

请求体：

响应：与 3.1 相同的账号对象。

说明：当前版本注册不需要邮箱验证码，注册完成即可登录，账号没有「待激活」状态。密码复杂度仅由前端校验，服务端未做强制约束，接入方如需约束请自行在业务侧实现。

3.3 更新账号

PUT /api/passport/service/v1/account

需要携带 Token。

请求体：

响应：

{
  "code": 0,
  "message": "success"
}

重要警告：该接口采用全量保存。请求体中不要携带 password 字段——若携带，提交的明文会直接覆盖数据库中的 BCrypt 密文，导致该账号永久无法登录。当前版本没有提供修改密码接口，修改密码请走「找回密码」流程（见 9.1–9.3）。

Account Profile 模块

4.1 查询用户资料

GET /api/passport/service/v1/account-profile

需要携带 Token。

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "1234567890",
    "name": "张三",
    "gender": "MALE",
    "birthday": "1990-01-01",
    "bio": "这是一段个人简介",
    "avatar": "/api/passport/service/v1/account-profile/avatar",
    "updatedTime": "2024-01-01 10:00:00"
  }
}

资料中不包含 email 与 phone，这两个字段属于账号（Account）而非资料（Profile）。

4.2 更新用户资料

PUT /api/passport/service/v1/account-profile

需要携带 Token。

请求体：

响应：

{
  "code": 0,
  "message": "success"
}

说明：资料的 id 由服务端从 Token 中取，不读取请求体中的 id，因此无法修改他人资料。

4.3 获取头像

GET /api/passport/service/v1/account-profile/avatar

需要携带 Token。返回当前账号的头像图片二进制流（新上传的头像为 image/webp）。

未上传头像时返回 HTTP 404，且不返回 JSON 响应体。

4.4 上传头像

POST /api/passport/service/v1/account-profile/avatar

需要携带 Token。使用 multipart/form-data 上传。

请求参数：

响应：

{
  "code": 0,
  "message": "success",
  "data": "/api/passport/service/v1/account-profile/avatar"
}

说明：服务端会将图片统一裁剪为 128×128 并转码为 WEBP 格式，存入对象存储（RustFS）；上传新头像会覆盖同账号的旧头像。

Query 模块

5.1 分页查询账号

GET /api/passport/service/v1/query/account

需要携带 Token。

请求参数：

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "1234567890",
        "userId": "user123",
        "name": "张三"
      }
    ],
    "pageNo": 1,
    "pageSize": 10,
    "totalCount": 100,
    "totalPage": 10
  }
}

分页查询仅返回 id、userId、name 三个字段，不包含邮箱、手机号等信息。如需完整账号信息，请先按 id 调用 3.1 查询账号接口。

分页字段说明：

Login History 模块

6.1 查询登录历史

GET /api/passport/service/v1/account/login-history

需要携带 Token。返回当前账号最近的登录记录。

响应：

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "accountId": "1234567890",
      "clientIp": "192.168.1.1",
      "loginMethod": "WEB",
      "LoginTime": "2024-01-01 10:00:00"
    }
  ]
}

Sync 模块

用于应用账号（SDK 接入方）同步自身应用下的 API 与权限定义。需要携带应用账号的 Token。

7.1 同步 API 列表

GET /api/passport/service/v1/sync/api

响应：

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "api123",
      "name": "查询用户",
      "path": "/api/user/*",
      "method": "GET",
      "description": "查询用户信息",
      "applicationId": "app123",
      "tenantId": "0",
      "creator": "admin",
      "updater": "admin",
      "createdTime": "2024-01-01 10:00:00",
      "updatedTime": "2024-01-01 10:00:00"
    }
  ]
}

说明：返回当前应用账号所属应用的 API 列表。若账号未绑定应用，返回空数组。

7.2 同步权限列表

GET /api/passport/service/v1/sync/permission

响应：

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "permission123",
      "name": "用户管理权限",
      "description": "用户管理相关权限",
      "applicationId": "app123",
      "applicationName": "用户服务",
      "riskLevel": "LOW",
      "apiCount": 5,
      "tenantId": "0",
      "creator": "admin",
      "updater": "admin",
      "createdTime": "2024-01-01 10:00:00",
      "updatedTime": "2024-01-01 10:00:00",
      "apiIds": ["api1", "api2", "api3", "api4", "api5"]
    }
  ]
}

说明：权限归属应用，字段为 applicationId / applicationName（早期版本中的 serviceId / serviceName 已废弃）。

7.3 同步标志

GET /api/passport/service/v1/sync/flag

该接口尚未实现，当前调用会返回 HTTP 500。请勿在生产环境依赖此接口。

Verify 模块

8.1 生成邮箱验证码

GET /api/passport/service/v1/verify?email=user@example.com

请求参数：

响应：data 为 null，验证码通过邮件发送。

{
  "code": 0,
  "message": "success"
}

8.2 生成滑块验证码

GET /api/passport/service/v1/verify/image

响应：返回滑块验证码素材，不是图片流。

{
  "code": 0,
  "message": "success",
  "data": {
    "key": "captcha:xxxxxxxx",
    "imageBase64": "iVBORw0KGgoAAAANSUhEUg...",
    "tileBase64": "iVBORw0KGgoAAAANSUhEUg...",
    "tileWidth": 60,
    "tileHeight": 60,
    "tileX": 120,
    "tileY": 45
  }
}

出于安全考虑，tileX（缺口横坐标）由服务端返回，接入方据此渲染初始位置并采集用户拖动轨迹。

8.3 校验滑块验证码

POST /api/passport/service/v1/verify/image

该接口使用表单格式（application/x-www-form-urlencoded），不是 JSON。

请求参数：

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "captchaToken": "captcha:token:xxxxxxxx",
    "ok": true
  }
}

说明：校验容差为 4 像素。ok 为 false 表示校验未通过，此时 captchaToken 为空。校验通过后返回的 captchaToken 用于登录（1.1）与找回密码（8.4），且为一次性凭证。

Forgot Password 模块

修改密码需通过以下三段式流程完成，该模块全部接口免 Token 校验。流程起点仍需先过滑块验证码。

9.1 发送验证码

POST /api/passport/service/v1/account/forgot-password/send-code

请求体：

响应：

{
  "code": 0,
  "message": "success"
}

失败时返回 HTTP 200 与对应的业务码（见「错误码」），例如 4001 Email not registered。

9.2 校验验证码

POST /api/passport/service/v1/account/forgot-password/verify-code

请求体：

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "resetToken": "xxxxxxxx"
  }
}

9.3 重置密码

POST /api/passport/service/v1/account/forgot-password/reset

请求体：

响应：

{
  "code": 0,
  "message": "success"
}

完整流程：

1. 调用 8.2 获取滑块验证码素材
2. 调用 8.3 提交滑块位置，换取 captchaToken
3. 调用 9.1（携带 captchaToken 与邮箱）发送邮件验证码
4. 调用 9.2（携带邮箱与邮件验证码）换取 resetToken
5. 调用 9.3（携带邮箱、resetToken、新密码）完成重置

Enterprise Account Activation 模块

企业账号（HR 同步或管理员创建）初始为「待激活」，员工凭企业邮箱验证码设置密码后激活。该模块全部接口免 Token 校验。验证码与邮件验证码共用同一发送通道，5 分钟有效。

10.1 发送激活验证码

POST /api/passport/service/v1/account/enterprise-activation/send-code

请求体：

响应：

{
  "code": 0,
  "message": "success"
}

失败时返回 HTTP 200 与 5001 No pending enterprise account for this email。同一邮箱 1 分钟内只允许发送一次（与注册验证码共享冷却窗口）。

10.2 接受邀请

POST /api/passport/service/v1/account/enterprise-activation/accept-invite

请求体：

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "email": "zhangsan@corp.com"
  }
}

接受邀请后 Passport 自动创建待激活的企业账号并发送验证码，后续走 10.3 激活流程。已存在的账号不会重复创建。

10.3 激活

POST /api/passport/service/v1/account/enterprise-activation/activate

请求体：

响应：

{
  "code": 0,
  "message": "success"
}

激活成功后账号转为已启用，可直接登录。验证码错误累计超过 5 次将被拒绝，需重新发送。

10.4 身份选择页数据

GET /api/passport/service/v1/identity-gate/:token

单点登录过程中个人身份访问企业应用且名下存在可选企业身份时，Passport 引导浏览器到身份选择页，页面凭 URL 中的 token 调用本接口获取展示数据（应用名、候选身份列表）。

10.5 切换身份

POST /api/passport/service/v1/identity-gate/:token/switch

请求体：

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "<新登录 token>",
    "continueUrl": "<原 authorize/SSO 地址>"
  }
}

服务端同时写入登录 Cookie，浏览器随后跳转 continueUrl 即以企业身份继续单点登录。gate token 为一次性凭证，切换成功后即作废。

错误码

通用

登录（Login）

以上错误码均伴随 HTTP 200 返回，请通过 body 中的 code 判断，不要只看 HTTP 状态码。

找回密码（Forgot Password）

企业账号激活（Enterprise Activation）

同样伴随 HTTP 200 返回。

管理端（passport-admin）

管理端服务使用独立的错误码空间：

认证流程

个人账号登录流程

1. 调用「用户登录」，携带登录名与密码（首次/上次成功后的登录无需验证码）
2. 若返回 10007（上次登录失败），先调用「生成滑块验证码」获取素材，再调用「校验滑块验证码」换取 captchaToken
3. 携带 captchaToken 重新调用「用户登录」
4. 保存返回的 token，后续请求在 passport-token 请求头或 passport_token Cookie 中携带

扫码登录流程

Web 端与扫码设备端的完整接入步骤见「扫码登录接入」的「接入清单」。

App 登录与续期流程

1. 调用「生成滑块验证码」+「校验滑块验证码」换取 captchaToken
2. 调用「App 登录」(1.3),安全保存返回的 token 与 refreshToken
3. access token 过期(或收到 401)时,调用「刷新 Token」(2.5)静默续期;刷新失败则回登录页
4. 登出时携带 refreshToken 调用 DELETE /login,服务端吊销后清除本地存储

应用账号换取 Token 流程

1. 调用「生成签名」，传入 accessKeyId 与 secretAccessKey，获得 signature 与 timestamp
2. 调用「生成 Token」，传入 accessKeyId、timestamp、signature
3. 保存返回的 Token 字符串，后续请求在 passport-token 请求头中携带
4. Token 有效期 24 小时且不支持续期，过期后重新执行本流程（SDK 已内置该流程与缓存，参见「SDK 集成」章节）

权限判断

Token 的 pids 声明中携带了账号被授予的权限 ID 列表。接入方有两种做法：

1. 直接解析 JWT 的 pids 声明（需持有公钥校验签名）
2. 调用「同步权限列表」接口获取权限定义，与 pids 比对

注意：Go SDK 当前版本不会解析 pids，AccountInfo.PermissionIds 字段恒为空，需自行解析。