鉴权

Poco 对外接口使用两类凭证：

• API Key：用于服务端调用对话、会话、产物或 Office Mode 接口。
• 登录 Token：代表某个 Poco 用户登录，可用于 Agent 外部嵌入等需要用户身份的页面或接口。

不要把账号密码、API Key 或固定登录 Token 写入浏览器端代码、URL、公开仓库或业务日志。

API Key 的使用方式

Chat Completions 与会话、运行、产物接口支持 Bearer，优先读取：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

也兼容：

x-api-key: sk-xxxxxxxxxxxxxxxxxxxx

Messages 只接受 x-api-key，仅传 Bearer 会返回 401。Office Mode 只接受 Authorization: Bearer <api_key>，且 Key 必须具有 admin scope。

Key 的 scope、执行目标和管理端点见 API Key 管理。管理 Key 与人工输入使用登录 Token，不能直接提交原始 API Key。对话调用的各类 Key 仍受用户及具体 Key 会话归属限制。

获取登录 Token

端点：POST /openapi/v1/auth/token

该接口支持账号密码、SSO Token 和 API Key 三种授权方式。Token 默认有效 24 小时，服务端可通过 OPENAPI_LOGIN_TOKEN_TTL_SECONDS 缩短有效期；请求方不能自行指定时长，也不会获得 Refresh Token。

账号密码

curl -X POST 'https://<poco-host>/openapi/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "password",
    "username": "<账号>",
    "password": "<密码>"
  }'

XGT SSO Token

如果已有 SSO 回调地址：

https://<poco-host>/zh/login?card=<工号>&token=<鉴权token>&redirect=<目标地址>

只需提取 token 参数：

curl -X POST 'https://<poco-host>/openapi/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "sso_token",
    "provider": "xgt",
    "sso_token": "<鉴权token>"
  }'

接口不接收也不信任 card。实际账号以 XGT 用户信息接口返回的 data.empNo 为准，data.secondUnit 会同步到用户部门；用户不存在时，按现有 SSO 默认团队、功能角色和场景配置创建。

API Key

curl -X POST 'https://<poco-host>/openapi/v1/auth/token' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"api_key"}'

API Key 换取登录 Token 时遵循以下规则：

• conversation scope 不能换取登录 Token。
• 普通用户使用 global scope，管理员使用 admin scope。
• 登录身份始终是 API Key 所属用户，不能指定其他用户。
• API Key 删除、过期或所属用户被禁用后，不能再签发 Token；用户禁用后，已签发 Token 也无法继续使用；Key 删除或过期不等于直接撤销独立签发的登录 Token。

响应

成功响应：

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 86400
}

业务错误响应：

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid credentials"
  }
}

成功、业务错误和请求校验错误都会包含：

Cache-Control: no-store
Pragma: no-cache

API Key 所属用户禁用时，API Key 授权返回 401；密码或 SSO 授权的禁用用户返回 403。

生产环境应在入口网关对 Token 端点配置 IP 和 API Key 维度的频率限制。登录 Token 过期后，重新执行原授权流程获取新 Token。