> ## 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.

# 身份验证

> 适用于所有 Theo API 端点的 API 密钥身份验证。

所有 API 端点（`GET /health` 除外）都需要在 `Authorization` 头中通过 Bearer 令牌进行身份验证。

## API 密钥格式

密钥以 `theo_sk_` 作为前缀进行标识：

```
theo_sk_a1b2c3d4e5f6...
```

所有密钥均为生产密钥——请求将从你的信用余额中计费。

## 发起已认证的请求

在每个请求中都需携带该密钥：

```bash theme={null}
curl https://www.hitheo.ai/api/v1/completions \
  -H "Authorization: Bearer theo_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello"}'
```

<Warning>
  务必调用 `www` 主机。顶级域名 `hitheo.ai` 会以 307 重定向到 `www.hitheo.ai`，而大多数 HTTP 客户端在遇到 3xx 响应时会剥离 `Authorization` 头——重定向后的请求会以未认证状态到达，并返回 `401`。完整说明参见 [401 故障排查](/troubleshooting/401-errors)。
</Warning>

使用 SDK 时，在初始化阶段传入该密钥：

```typescript theme={null}
import { Theo } from "@hitheo/sdk";

const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });
```

## 密钥管理

可通过 [API 控制台](https://api.hitheo.ai) 或 API 创建和管理密钥：

```bash theme={null}
# 创建一个密钥
curl -X POST https://www.hitheo.ai/api/v1/keys \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Server"}'
```

## 首次运行诊断

如果第一次调用就出现问题，在排查日志之前先运行 SDK 验证器：

```bash theme={null}
# CLI —— 输出结构化 JSON，失败时退出码为 1
theo verify
```

```typescript theme={null}
// SDK —— 返回 { healthy, authenticated, baseUrl, latencyMs, error?, hint? }
const result = await theo.verify();
if (!result.authenticated) console.error(result.hint);
```

常见故障模式及其修复方法参见 [401 故障排查](/troubleshooting/401-errors) 页面。

## 安全最佳实践

<Warning>
  切勿在客户端代码、公共代码仓库或日志中暴露 API 密钥。
</Warning>

* 将密钥存放在环境变量或密钥管理器中
* 开发环境使用测试密钥（`theo_sk_test_`）
* 定期在控制台中轮换密钥
* 为每个密钥设置速率限制和消费上限

## 错误响应

| 状态码 | 错误代码 | 说明 |
| - | - | - |
| 401 | `invalid_api_key` | 密钥缺失、格式错误或已被吊销 |
| 402 | `insufficient_credits` | 账户余额不足 |
| 429 | `rate_limit_exceeded` | 请求过于频繁——请检查 `Retry-After` 头 |


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