认证与 API Key

Key 形态

TokenHouse 的 API Key 以 sk-tokenhouse_ 开头，后接随机串：

sk-tokenhouse_xxxxxxxxxxxxxxxxxxxxxxxx

所有请求通过 HTTP 头携带：

Authorization: Bearer <your-key>

网关支持通过 Authorization: Bearer 头（推荐）或 Anthropic 原生的 x-api-key 头传入你的 Key——两种方式均可用于 Anthropic 原生 SDK 和 Claude Code（见 Anthropic SDK 与 Claude Code）。

可以用 GET /v1/models 快速验证 Key 是否可用（需鉴权，以 OpenAI list 格式返回当前可调用的模型列表）：

curl https://api.tokenhouse.ai/v1/models \
  -H "Authorization: Bearer <your-key>"

Key 与组织

  • 每把 Key 都归属于一个组织，而不是个人账号。
  • 通过 Key 产生的所有消费都从该组织的共享预付费余额池扣除，余额与充值见余额与充值。
  • 组织成员的邀请与管理在成员管理页面进行。
  • 同一组织可创建多把 Key，分别用于不同应用 / 环境，用量与撤销的影响面都以单把 Key 为边界。

创建与撤销

在 API Keys 页面创建、查看（后四位）、撤销 Key。

  • Key 明文仅创建时显示一次，请立即妥善保存——之后无法再次查看。
  • 撤销后 Key 立即失效，但历史用量与计费记录保留。怀疑泄露时先撤销，再重建。

安全最佳实践

  • 环境变量注入：通过环境变量或密钥管理工具传入 Key，不要硬编码在源码里。
  • 按环境拆 Key：开发 / 测试 / 生产各用独立 Key，单把泄露或轮换不影响其它环境。
  • 泄露立即撤销重建：在 API Keys 撤销旧 Key、创建新 Key，撤销即刻生效。
  • 不要提交进 git：把 .env 等含 Key 的文件加入 .gitignore；明文一旦进过提交历史，即使删掉提交也应视为已泄露并撤销。

Key 明文只在创建时显示一次。任何之后还能读到明文的地方——聊天记录、CI 日志、截图——都意味着 Key 已经离开了安全边界。

常见鉴权错误

HTTPcode含义
401missing_or_malformed缺少或格式错误的 Authorization 头
401invalid_api_keyKey 无效
401key_revoked_or_disabledKey 已撤销或被禁用

401 响应体示例（所有错误统一为 { "error": { "type", "code", "message" } } 结构）：

{
  "error": {
    "type": "auth_error",
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}

完整错误码见错误码与计费。