业务方系统间调用方案

适用场景：A 系统、B 系统的用户登录都走知办登录（手机号验证码或账号密码），A 调 B 时希望 B 能确认“请求里的知办登录 token 合法、属于同租户、对应哪个用户”，再由 B 自己做接口权限判断。

推荐链路

用户
  │ 登录 A / B 均走知办用户登录
  ▼
A 系统拿到知办登录 access_token
  │
  │ A 调 B: Authorization: Bearer <知办用户 access_token>
  ▼
B 系统后端
  │
  │ POST /api/external/v1/auth/introspect
  │ Authorization: Bearer <B 系统 ek_ API Key>
  │ {"token":"<知办用户 access_token>"}
  ▼
Agent Bus
  │ 校验签名 / 过期 / 撤销 / API Key 租户一致性
  ▼
B 系统拿到 account_id / account_uuid / tenant_id / perms
  │
  └─ B 按自己的业务接口权限继续判断

Token Introspection 接口

POST /api/external/v1/auth/introspect

调用方必须是被调用方系统的后端服务，使用租户 API Key（ek_）调用，并且 API Key 需要勾选 tenant.auth.introspect scope。不要从浏览器或移动端直接调用该接口。

请求示例：

curl -sX POST "$ZHIBAN_BASE_URL/api/external/v1/auth/introspect" \
  -H "Authorization: Bearer $B_SYSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"'"$ZHIBAN_USER_ACCESS_TOKEN"'"}'

有效 token 响应：

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {
    "active": true,
    "account_id": 123,
    "account_uuid": "account_uuid",
    "tenant_id": 617,
    "workspace_id": 44,
    "act_scope": "tenant:tenant_uuid",
    "session_uuid": "session_uuid",
    "perms": ["tenant.agent.read"],
    "perms_hash": "hash",
    "kind": "user",
    "issuer": "https://zhiban.example.com",
    "subject": "account_uuid",
    "issued_at": 1783000000,
    "expires_at": 1783000900,
    "cache_ttl_seconds": 60
  }
}

无效、过期、撤销、跨租户 token 统一返回：

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {
    "active": false
  }
}

Python SDK 示例

from zhiban_agent_sdk import ZhibanClient

client = ZhibanClient.from_api_key(
    "https://zhiban.example.com",
    "ek_b_system_api_key",
)

result = client.auth.introspect(user_access_token)
if not result.active:
    raise PermissionError("invalid zhiban user token")

tenant_id = result.tenant_id
account_uuid = result.account_uuid

安全边界

• B 系统只能 introspect 与自己 API Key 同租户的用户登录 token；跨租户统一返回 active=false，不返回用户信息。
• tenant_id、account_id、account_uuid 只能信任 Agent Bus introspection 响应，不能信任 A 系统额外传的 header/body。
• B 系统拿到 token 身份后，仍要按自己的业务权限判断接口是否允许访问；introspection 只解决“这个知办用户是谁、token 是否有效”。
• 可按 sha256(token) 本地缓存 introspection 结果，缓存时间不超过响应里的 cache_ttl_seconds；高风险写操作建议实时校验。
• 业务日志不要打印原始用户 token 或 ek_ API Key。

行业最佳实践与知办适配

• 行业做法：OAuth 2.0 Token Introspection（RFC 7662）用于资源服务器向授权服务器查询 token 是否 active；JWT Access Token Profile（RFC 9068）适合自包含 access token；Token Exchange（RFC 8693）适合跨受众换一张新 token。
• 知办当前上下文：用户登录 token 由 Agent Bus 签发并管理撤销，A/B 系统都把 Agent Bus 当鉴权中心；调用频繁、链路需要短。
• 采用方案：v1 采用后端 introspection，保留服务端撤销、租户一致性校验和最小权限 API Key scope。
• 暂不采用项：不把知办私钥或 JWKS 验签能力直接作为唯一方案下发给业务方；不强制 A 调 B 前先做 Token Exchange，避免高频系统间调用链路过长。