身份验证

API Key 格式

Token101 使用 API Key 对 API 流量做身份验证，而且校验规则刻意保持简单。服务端会拒绝任何不以 sk- 开头、或者总长度少于 32 个字符的 key。这意味着对所有 client 集成来说，最安全的默认策略都是一样的：把完整 key 当成不可解释的 secret string 处理，保留前缀，不要在存储前后擅自裁剪空格。

因此，一个有效 key 在高层上应满足：

• 前缀：sk-
• 总长度下限：32 个字符
• 传输方式：按签发时的完整值原样发送

不要从可见前缀里推断业务含义，也不要在 client 应用中依赖部分 key 匹配。Key 是凭证，不是标识符。如果你确实需要对它们做运维标记，请使用 dashboard 元数据或你自己的 secret manager 命名规则，而不是解析 key 本体。

身份验证方式

所有发往 messages endpoint 的请求，都必须通过 Bearer scheme 在 Authorization header 中携带 key：

curl https://token.ppthub.shop/api/v1/messages \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $TOKEN101_API_KEY" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 128,
    "messages": [
      {
        "role": "user",
        "content": "Return a one-line authentication check."
      }
    ]
  }'

Token101 也会受理放在 x-api-key header 中的 key（这是 Anthropic SDK 的原生行为）——因此仅用 API key 配置的 SDK 同样能完成鉴权。上面的 Bearer 写法仍是推荐写法；当两者同时存在时，以 Bearer token 优先。

每个请求都必须携带有效凭证。如果两种 header 都没有携带有效 key——header 缺失、Authorization 的值不以 Bearer 开头、或 key 未通过校验——Token101 会在处理请求之前直接返回 401 authentication_error。这种尽早失败的模式很有用，因为它能让 auth 问题和内容或计费问题清晰分离。

配合 SDK 使用

如果你只使用原始 HTTP，请求方式到上一节就已经够用。如果你是在应用代码里集成，请把 SDK 配置集中一次完成，并把 key 保存在 environment variables 中。Token101 适配 Anthropic SDK，通过自定义 base URL 接入。

Python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["TOKEN101_API_KEY"],
    base_url="https://token.ppthub.shop/api",
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=128,
    messages=[
        {
            "role": "user",
            "content": "Return a one-line authentication check.",
        }
    ],
)

print(message.content[0].text)

JavaScript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.TOKEN101_API_KEY!,
  baseURL: 'https://token.ppthub.shop/api',
});

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 128,
  messages: [
    {
      role: 'user',
      content: 'Return a one-line authentication check.',
    },
  ],
});

console.log(message.content[0]?.text);

base URL 的区别很重要。对 curl 和其他直接 HTTP client，使用 https://token.ppthub.shop/api/v1/messages。对 Python 和 JavaScript SDK client，使用 https://token.ppthub.shop/api 作为 base_url 或 baseURL，然后让 SDK 自动拼接 Claude-compatible path。把这两种模式混在一起，是最常见也最没必要的 404 或 malformed request 来源之一。

API Key 管理

请在 dashboard 的 API Keys 设置页创建 key，并围绕“每个 app、environment 或 automation 一个 key”来设计运维流程。这样做可以在 key 泄露时把影响范围控制得更清楚，也能在使用量突然变化时，更容易读懂审计轨迹。

轮换时，推荐使用一个受控的三步流程：

1. 创建一个新的 API Key。
2. 更新所有 deployment、worker 或 CI job，让它们改用新的 secret。
3. 在确认切换完成后，禁用或删除旧 key。

不要在缺乏 rollout 追踪的情况下，直接原地编辑某个 secret 值。API 会对每个请求实时校验 key，所以一旦旧 key 失效，任何尚未更新的 deployment 都会立刻开始返回 401 authentication_error。短时间的重叠窗口可以接受；没有记录的重叠窗口不可以。

如果某个 key 已经不再需要，请在 dashboard 中通过禁用或删除的方式完成 revoke。对于 incident response、员工离职或 environment 下线，这一步应该立即执行。被撤销的凭证会立即失效，没有宽限期。

安全最佳实践

即使在开发环境中，也要把每一个 API Key 当成 production-sensitive secret 处理。最简单、也最可靠的安全基线是：

• 把 key 存放在 environment variables 或 secret manager 中。
• 永远不要把 key 提交到 Git、截图、工单或聊天记录里。
• 不要让不相关的多个服务共用同一个 key。
• 一旦怀疑泄露，就轮换 key，而不是只按固定周期轮换。
• 监控使用量变化，尽早发现意外循环调用或 credential 泄露。

在本地工具里，优先把 TOKEN101_API_KEY 放进 .env.local 或 shell profile，并保证 .env* 规则已经加入 .gitignore。在 server-side 应用里，应该在部署阶段注入 secret，而不是把它打包进 client。Token101 默认假设 key 由服务端控制；如果你把它暴露到浏览器代码里，本质上就是把每个访客都变成了你的 API client。

错误处理

大多数和 auth 相关的失败，都会返回标准 JSON envelope：

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

最值得优先处理的几类情况如下：

部分 429 响应还会带上 Retry-After、X-Token101-Policy-Gate 和 X-Token101-Policy-Reason 这类 policy header。请把客户端写成“有条件的重试”，而不是“默认自动重试”。如果你对每个 401 或 403 都无脑重试，你会把一个 auth 故障放大；如果你在 429 时忽略 Retry-After，你就会把短暂的 quota 边界变成自我制造的流量尖峰。

如果你不确定该从哪里开始排查，请按这个顺序来：先验证完整的 Authorization: Bearer ... header，再确认 dashboard 中该 key 仍然存在，最后把响应结果和 Quick Start、Error Handling、Rate Limits 对照。这样的排查顺序能把排查建立在实际 API 行为之上，而不是猜测。