鉴权与密钥

所有公开 Gateway 请求都使用 App API Key。Host 选择链、网络和协议，API Key 选择 App；同一个有效 Key 可以访问该 App 下已启用且已配置路由的 Gateway。

Bearer 鉴权

推荐服务端应用使用 Bearer Header，避免 Key 出现在 URL 和访问日志中：


curl 'https://ether-jsonrpc.<gateway-domain>' \
  -H 'Authorization: Bearer <app_api_key>' \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Authorization 必须是恰好两段的 Bearer <key>。

Path Key

需要把完整 RPC URL 交给 SDK 时，可以把 Key 放在第一段路径：


https://ether-jsonrpc.<gateway-domain>/<app_api_key>
https://tron-httpapi.<gateway-domain>/<app_api_key>/wallet/getnowblock

Path Key 方便直接配置客户端，但更容易进入代理访问日志、浏览器历史或监控系统。只在能保护完整 URL 时使用。

如果同时发送 Path Key 和 Bearer Key，两者必须完全一致，否则鉴权失败。

不支持的传递方式

不要通过以下位置发送 App API Key：

Query 参数；
Cookie；
自定义 Header；
JSON-RPC 请求体。

Key 状态与轮换

Active：正常使用。
Grace：轮换后旧 Key 在宽限期内继续有效，便于无中断更新客户端。
Expired：宽限期结束，不再接受。
Revoked：立即失效。

推荐轮换流程：创建新 Key，更新所有实例，验证新 Key，再撤销旧 Key。不要在客户端切换完成前提前撤销。

App 被禁用、Account 不再有效、Key 过期或被撤销时，认证都会失败。JSON-RPC 返回错误码 -32001；TRON HTTP API 返回 HTTP 401。

安全建议

使用 Secret Manager 或运行时环境变量保存 Key。
不要提交到 Git，不要写入前端代码或移动端安装包。
日志只记录内部 Key ID，不记录完整 Key 或包含 Key 的 URL。
泄漏时立即轮换并撤销旧 Key。