每个请求都应该让它的认证方式一目了然。即使实际方案以后发生变化,读者也需要有一个明确的地方,清楚说明需要什么凭证,以及它们应该放在哪里。

Header 格式

对需要认证的调用,请使用专门的授权头:

Authorization: Bearer <token>

在所有示例中保持 Header 大小写和 token 前缀一致,这样参考文档会更容易直接复制使用。

这里应该记录什么

至少,这个页面应该回答这些问题:

  • 客户端如何获取 token
  • token 是否带作用域,或是否与环境绑定
  • 哪些路由允许匿名访问
  • 过期凭证会如何被报告

交叉链接

认证说明通常还需要一个配套指南,用来解释本地设置或凭证轮换。把这类操作型说明放在 /docs 中,然后再链接回这里,给出精确的 header 约定。