用途：说明平台 API 网关如何前置某个服务。网关终止认证，用组织 IDP 校验调用方令牌，并把已核实的身份以请求头下传给服务，服务代码因此从不接触令牌。
主要规则：服务端绝不校验 JWT——签名密钥、client_id 和 IDP 发现地址都在平台侧；也绝不签发令牌，不提供 /auth/login、/auth/register、/auth/logout 或任何后端令牌端点，令牌签发由 IDP（见 thunder-authentication）负责。
身份头：X-User-Id（对应 sub，受保护请求中始终存在）、X-User-Groups（groups，JSON 数组，用户在任一角色组时存在）、X-User-Name（username，可能缺失）、X-User-Ou（ouHandle，多租户，可选）。因由网关依据已校验令牌设置，客户端无法伪造。受保护请求缺少 X-User-Id 时返回 401；已认证但无角色的调用方返回 403 而非 401（401 会让 SPA 认为令牌过期并反复重启登录）。
数据归属：以 X-User-Id 标记本服务创建的每一行，并按它约束所有按用户查询，例如 WHERE id = ? AND user_id = ?，更新和删除同理；查询无匹配应为 404 而非 500。
CORS：api-configuration 的 ClusterTrait 会按可见性挂载 Envoy CORS 过滤器（visibility: external），受管 API 不得再加自己的中间件，否则头部重复。
文档：为受保护服务编写的 OpenAPI 中，应把 X-User-Id 列入 parameters，说明它由网关注入、客户端不设置。
调用上游：转发调用方认证到上游 bearer API 时，原样传递入站 Authorization 头，不要重新签发令牌。
测试：测试请求不会带 X-User-Id，需在测试中直接设置该头，而不是尝试铸造 JWT。
限制：以上均以资料所述网关契约为准；具体语言路由风格、公共 helper 位置与状态码返回方式需沿用对应技术栈既有约定，资料未提供具体代码样例。