GET/api/v1/admin/auth/session
管理员Cookie,ADMIN_SESSIONJSON 响应接入指南 ↗

读取管理员会话

请求参数

仅后台web客户端。必须使用HTTPS和JWE;八项公共元数据必填,clientType=admin、platform=web、channel=admin_web。客户端类型不是管理员认证,App Bearer不能调用后台。

无查询参数或正文。

请求示例

通过管理员统一请求约定加密后发送,下面表示解密后的业务内容。外层使用Accept: application/jose;GET无正文,密文置X-Budyoo-JWE。写请求Origin必须与后台源一致,会话操作另带X-Admin-CSRF;HttpOnly Cookie由浏览器自动携带。

无业务JSON正文;查询参数按上表发送。

成功响应

HTTP200,Cache-Control:no-store。实际外层为JWE,解密后示例:

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "username": "admin",
    "role": "OWNER",
    "mustChangePassword": false,
    "expiresAt": "2026-11-03T20:00:00Z",
    "permissions": [
      "ADMIN_SESSION",
      "ADMIN_USERS_READ",
      "ADMIN_USER_PROFILES_READ",
      "ADMIN_USER_PROFILES_WRITE",
      "ADMIN_CONFIG_READ",
      "ADMIN_CONFIG_WRITE",
      "ADMIN_AUDIT_READ",
      "ADMIN_VERSIONS_READ",
      "ADMIN_VERSIONS_WRITE",
      "ADMIN_AGREEMENTS_READ",
      "ADMIN_AGREEMENTS_WRITE",
      "ADMIN_ENFORCEMENT_READ",
      "ADMIN_ENFORCEMENT_WRITE"
    ],
    "csrfToken": "64位会话CSRF令牌"
  },
  "errors": []
}

浏览器刷新后恢复当前会话,并取得写请求CSRF。返回id、username、role、mustChangePassword、expiresAt、permissions和csrfToken;凭证不写localStorage。

同一浏览器关闭后重新打开也通过本接口恢复。登录选择rememberMe=true的会话固定30天有效,不受30分钟空闲限制;其他会话仍为8小时绝对期限及30分钟空闲期限。恢复会话只刷新last_seen_at,不续期、不重设Cookie,expiresAt始终是原登录的绝对期限。退出、改密、安装不匹配、停用或到期后返回401并要求重新登录;清理浏览器Cookie或安装ID也不能恢复。

失败响应

HTTP code 条件
400 BAD_REQUEST/VALIDATION_FAILED JSON、查询参数或字段校验失败
400 INVALID_CLIENT_HEADERS 元数据缺失/重复/不合法
400 ENCRYPTION_REQUIRED/INVALID_ENCRYPTED_REQUEST 缺少真实JWE或认证失败
401 UNAUTHORIZED 会话无效、失效、安装不匹配或误用App凭证
403 FORBIDDEN/ADMIN_CSRF_INVALID 权限不足、来源或CSRF不符
426 HTTPS_REQUIRED 通过HTTP发送后台请求
429 TOO_MANY_REQUESTS 来源IP或网关限流
503 SERVICE_UNAVAILABLE 持久存储或Redis依赖不可用

错误按四语公共协议返回,不泄露密码、Cookie或内部异常;无法解密前的错误没有加密响应上下文,不作为已认证业务结果。

接入说明

mustChangePassword为兼容保留字段,当前固定false,不再限制权限或页面跳转;有效账号登录后直接按OWNER/VIEWER角色访问后台。保持登录不重置用户当前密码,也不改变OWNER/VIEWER授权。

所有安全和会话约定见后台登录协议,权限由后端每次请求核验。正式凭证不通过未信任TLS链路发送。已通过服务器隔离数据库回归,覆盖独立身份、权限、字段校验和对应失败分支;旧环境曾使用已明确信任的IP证书完成浏览器登录、改密、列表、配置及审计检查。保持登录新增11项隔离回归,覆盖真实JWE、30天固定期限、普通会话默认值、严格布尔值、退出/改密撤销、安装/停用/角色、CSRF/Origin、最多5会话以及V20→V21历史数据兼容。线上通过显式受信TLS和真实JWE验证:勾选保持登录为30天Cookie,取消为8小时Cookie;刷新及关闭整个浏览器后重开可恢复,退出清除Cookie且受保护页面回到登录。候选及线上各16组中英日韩/四种宽度布局通过。当前域名公共CA证书已签发,后台公网入口已发布并完成服务器内TLS校验,管理员创建/角色编辑页面仍待实现。