开始
认证
每个账户一个 bearer 密钥，暴露执法数据的接口另需 KYB，以及为什么 401 和 403 不是一回事。
请求头
每个请求以 bearer token 携带密钥。
GET /v1/coverage HTTP/1.1
Host: api.foreshock.org
Authorization: Bearer fsk_EXAMPLE_0000000000000000
Accept: application/json密钥是机密。不要进版本库、不要进 query string、不要进日志。
密钥的作用域
一个密钥只对应一个客户账户。跨客户读取不是「被拒绝」，而是不可表达：customer_id 是所有客户数据表的分区键与主键首列，一个密钥在原理上就寻址不到另一个账户的数据。
需要 KYB 的接口
契约中标注 x-kyb-required: true 的接口，还要求账户已完成机构 KYB 验证。v1 里是 GET /v1/exposure、GET /v1/coverage 与 POST /v1/decide/deposit。
非终态的执法数据在任何套餐下都不向未验证账户开放。这是产品边界，不是价格档位。
401 与 403 不同，而且这个区别重要
| 状态码 | type | 含义 | 该怎么做 |
|---|---|---|---|
401 | .../unauthorized | 密钥缺失、格式错误或已吊销。 | 停。不要用同一个密钥重试。叫人。 |
403 | .../kyb-required | 密钥有效；账户未完成 KYB。 | 停。重试解决不了。 |
403 | .../forbidden | 密钥有效，但对这个具体资源没有权限。 | 检查该资源是否属于本账户。 |
未验证账户上的有效密钥拿到的是 403，不是 401。如果你的客户端把两者合并成「认证失败，重试」，它就会对着一个只有人能解除的条件无限重试。
裁决路径上的认证失败
POST /v1/decide/deposit 上的认证失败不是裁决。任何非 2xx 响应里都没有裁决。无论状态码是什么，这笔入金在收到 200 之前一直是 HOLD。