> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 401 未授权

> Theo API 首次请求出现 401 错误的常见原因及修复方法。

如果你对 Theo API 的第一次请求返回 `401 Unauthorized`，几乎总是下面几种原因之一。请按顺序逐一排查。

## 1. apex → www 重定向（最常见）

`https://hitheo.ai` 会以 307 重定向到 `https://www.hitheo.ai`。大多数 HTTP 客户端——包括 Node 18 内置的 `fetch`、未加 `--location-trusted` 的 curl，以及若干语言运行时——出于安全考虑会在 3xx 响应上剥离 `Authorization` 头。这会导致重定向后的请求变成未认证请求，服务器因此正确地返回 `401 invalid_api_key`。
**修复方法：** 直接使用规范的 `www` 主机。自 `@hitheo/sdk@0.2.0` 起，SDK 默认使用 `https://www.hitheo.ai`；如果你手动固定了 `baseUrl`，请更新它：

```typescript theme={null}
// Before
new Theo({ apiKey, baseUrl: "https://hitheo.ai" })

// After
new Theo({ apiKey, baseUrl: "https://www.hitheo.ai" })
// or: omit baseUrl entirely to pick up the default.
```

对于原始 curl：

```bash theme={null}
# Use www directly
curl -H "Authorization: Bearer $THEO_API_KEY" https://www.hitheo.ai/api/v1/models
```

CLI 的诊断命令会自动检测到这一问题：

```bash theme={null}
theo status   # probes both apex and www, warns when your baseUrl is a redirect target
theo verify   # machine-readable JSON diagnostic you can pipe into CI
```

## 2. 缺失或格式错误的 API 密钥

除 `GET /api/v1/health` 之外，每个请求都需要一个 `Authorization: Bearer theo_sk_...` 头。请检查：

* 头名称必须恰好是 `Authorization`，而不是多了一个冒号的 `authorization:`，也不是 `X-API-Key`。
* 令牌前缀必须是 `theo_sk_`（不存在 `theo_sk_test_` 这种变体——所有密钥都是生产密钥）。
* 令牌前后不能有空白字符——`.env` 文件末尾遗留的换行符是常见原因。
* 密钥没有被撤销。请检查 [API Keys 控制台](https://api.hitheo.ai/dashboard/api-keys)。

## 3. 密钥的作用域不正确

API 密钥携带作用域（`completions`、`skills`、`tools`、`connectors`、`billing`）。缺少 `completions` 作用域的密钥会返回 `403 missing_scope`，而不是 `401`。如果你看到的确实是 `403`：请重新签发一个具备所需作用域的密钥，或联系密钥创建者对其进行更新。

## 4. 密钥已过期（宽限期已结束）

当你轮换密钥时，旧密钥会进入一个宽限窗口（可配置，默认 60 分钟），随后被撤销。使用已过期密钥发出的请求会返回 `401 key_expired`。请在控制台或通过 `POST /api/v1/keys/rotate` 完成轮换，并将新令牌替换到你的密钥存储中。

## 5. 时钟偏差导致 webhook 的 HMAC 校验失败

这与 API 密钥认证无关，但有时会被误报为「webhook 上的 401」：webhook 签名校验使用的是 `Theo-Signature` 头，它是对请求体做 HMAC-SHA256 计算得到的。如果你的服务器时钟偏差超过 5 分钟，签名就会校验不通过。可运行 `ntpdate -q pool.ntp.org` 进行检查。

## 仍未解决？

* 运行 `theo verify`（或在 SDK 中调用 `await theo.verify()`），并将输出提供给支持团队。
* 在工单中附上响应头 `X-Request-Id`——每个 v1 响应都会携带该头，成功响应还会在 JSON 响应体中以 `request_id` 字段暴露它。支持团队可据此在日志中查找该请求。
* 查看 [status.hitheo.ai](https://status.hitheo.ai) 是否有正在发生的事件。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.