实时会话上下文

本文档描述面向终端用户 Access Token 的实时会话上下文接口。

它用于解决以下问题：

登录时 Access Token claims 是快照，不能反映最新组织关系
管理员修改用户资料、组织关系、管理员标记后，第三方系统需要实时刷新
第三方系统需要同时拿到当前用户、当前应用、当前组织和可访问组织列表

如果你只需要标准 OIDC claims，请使用 /oidc/userinfo。如果你需要实时权限和组织状态，请优先使用本页接口。

接口地址

http

GET /api/session/context

认证方式

请求头必须带终端用户 Access Token：

http

Authorization: Bearer <access_token>

Query 参数

参数	必填	说明
`organization_id`	否	希望以哪个组织作为当前上下文返回结果

规则：

传了 organization_id：后端会严格校验当前用户此刻是否仍属于该组织
没传 organization_id：后端优先按当前 token 中已有组织上下文返回
如果 token 中组织上下文已失效，接口不会偷偷切到别的组织，而会返回 organization = null

成功响应

json

{
  "code": 0,
  "message": "success",
  "result": {
    "tenant": {
      "id": "tenant_xxx",
      "slug": "acme",
      "name": "Acme"
    },
    "user": {
      "id": "user_xxx",
      "username": "admin",
      "name": "刘少凡",
      "email": "demo@example.com",
      "phone_number": "13565265908",
      "avatar": "https://example.com/avatar.png",
      "updated_at": 1771311069
    },
    "application": {
      "id": "app_xxx",
      "name": "示例前端应用",
      "type": "SPA",
      "tenant_id": "default"
    },
    "organization": {
      "id": "org_xxx",
      "name": "伊犁绿鸟网络科技有限公司",
      "logo_url": "https://example.com/logo.png",
      "is_member": true,
      "is_admin": true,
      "roles": ["admin", "member"]
    },
    "organizations": [
      {
        "id": "org_xxx",
        "name": "伊犁绿鸟网络科技有限公司",
        "logo_url": "https://example.com/logo.png"
      }
    ],
    "session": {
      "subject": "user_xxx",
      "client_id": "app_xxx",
      "scopes": [
        "openid",
        "profile",
        "urn:codebird:scope:organizations"
      ],
      "current_organization_id": "org_xxx"
    }
  }
}

字段说明

`user`

当前登录用户的最新资料：

字段	说明
`id`	用户 ID
`username`	用户名
`name`	姓名 / 显示名称
`email`	主邮箱
`phone_number`	主手机号
`avatar`	头像地址
`updated_at`	用户资料更新时间，Unix 秒级时间戳

`application`

当前 Access Token 对应的应用信息，由后端根据 token 中的 client_id 自动识别：

字段	说明
`id`	应用 ID
`name`	应用名称
`type`	应用类型，如 `SPA`
`tenant_id`	应用所属租户

`tenant`

当前终端用户认证上下文所属租户：

字段	说明
`id`	租户 ID
`slug`	租户路径标识，用于 `/t/{tenant.slug}/...`
`name`	租户名称

`organization`

当前组织上下文。如果当前没有有效组织上下文，则为 null。

字段	说明
`id`	组织 ID
`name`	组织名称
`logo_url`	组织 Logo
`is_member`	当前用户是否仍属于该组织
`is_admin`	当前用户是否为该组织管理员
`roles`	当前用户在该组织下的角色列表

roles 只是角色列表。是否为组织管理员，请以 is_admin 为准，不要再根据 roles 中是否包含 admin 推断。

`organizations`

当前用户此刻仍可访问的组织列表。
如果管理员把用户移出某个组织，这里会立刻消失。

`session`

当前 token 的轻量会话信息：

字段	说明
`subject`	当前 token 关联的用户 ID
`client_id`	当前 token 对应的应用 ID
`scopes`	当前 token scopes
`current_organization_id`	当前实际生效的组织上下文

什么时候应该使用本接口

建议在以下场景优先使用 /api/session/context：

页面首次加载时拉取最新用户资料
进入组织相关页面前确认用户是否仍属于该组织
切换当前组织后刷新上下文
执行关键权限操作前确认组织管理员状态和角色状态
管理员刚在后台调整了用户组织关系、管理员身份或角色权限

与 `/oidc/userinfo` 的区别

能力	`/oidc/userinfo`	`/api/session/context`
标准 OIDC claims	是	否
轻量用户信息	是	是
应用信息	否	是
当前组织成员关系是否仍有效	否	是
当前组织管理员是否实时最新	否	是
可访问组织列表是否实时最新	否	是

常见错误

HTTP 状态 / 业务语义	含义	推荐处理
`401` / 会话无效	Access Token 失效、过期或用户已失效	重新登录
`403` / 当前组织不存在或你已无权访问	显式传入的 `organization_id` 当前已无权限	重新选择组织
`404` / 当前应用不存在或已失效	token 对应应用已失效	联系管理员检查应用配置

SDK 封装

如果你使用官方 SDK，不需要手写本接口请求：

React SDK：参见 React SDK 集成教程
Go SDK：参见 Go Verifier SDK 集成教程

实时会话上下文 ​

接口地址 ​

认证方式 ​

Query 参数 ​

成功响应 ​

字段说明 ​

user ​

application ​

tenant ​

organization ​

organizations ​

session ​

什么时候应该使用本接口 ​

与 /oidc/userinfo 的区别 ​

常见错误 ​

SDK 封装 ​