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