Enterprise API 总览

Enterprise 暴露三类 HTTP API：

约定

认证

• Portal JWT：登录/SSO 后写入 httpOnly cookie；API Route 从 session 读取 claims
• Admin Session：独立 cookie，由 ADMIN_CONSOLE_SESSION_SECRET 签名
• Gateway：Authorization: Bearer <portal_jwt>，公钥 AUTH_JWT_PUBLIC_KEY
• Internal：Authorization: Bearer <GATEWAY_INTERNAL_TOKEN>

错误格式

Next.js API 通常返回：

1{ "error": "error_code", "message": "human readable" }

Gateway 业务错误使用 9xxxx 系列（策略拦截、配额超限等），与上游 OpenAI 错误区分。

多租户

几乎所有写操作隐式绑定 JWT 中的 tenant_id。Internal API 返回当前部署单租户或全量配置（由 store 实现决定）。

路由统计

OpenAI 兼容面

前台聊天最终打到 Gateway：

1POST /v1/chat/completions   # 含 SSE stream
2POST /v1/embeddings
3GET  /healthz
4GET  /internal/channel-stats  # 需 internal token

Portal 不直接暴露 OpenAI API，而是 /api/chat/completions 代理并注入审计所需 headers。

代码位置

类型契约见 packages/core-api/。

环境变量总表：../configuration/env-vars.md。