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

# 身份验证

> 如何使用 API 密钥 Hostlinku、其有效期、每个 API 密钥的额度以及相关安全措施

网关 Hostlinku 使用 **Bearer token** 身份验证，API 密钥格式为 `sk-…`。向 `/v1/*` 端点发送的每个请求中都应包含该 API 密钥：

```http theme={null}
Authorization: Bearer sk-your-api-key
Content-Type: application/json
```

对于端点 [Anthropic Messages](https://docs.hostlinku.com/zh/anthropic-messages.md)，也接受 `x-api-key: sk-…` 标头。

API密钥可在[console.hostlinku.com](https://console.hostlinku.com)的**API密钥**菜单中创建和管理。

API密钥仅适用于 /v1/\*

API密钥**仅**在以下网关端点上有效：`/v1/chat/completions`、`/v1/messages`、`/v1/responses` 和 `/v1/models`。 控制台账户端点（`/api/*` - 个人资料、API密钥列表、日志、余额、管理员）**不接受** `403 API_KEY_NOT_ALLOWED` 的 API 密钥，且只能通过控制台登录会话访问。 相反，登录会话（cookie）在 `/v1/*` 上**无效**-网关始终会要求提供 API 密钥（`401`）。 因此，泄露的 API 密钥仅可用于调用模型（受余额、额度和速率限制的约束），无法读取账户数据、创建新 API 密钥或更改设置。

## 创建 API 密钥

1. 打开控制台 → **API密钥** → **创建API密钥**。
2. 请填写**名称**、可选的**有效期**以及可选的**额度**。
3. 复制显示的密钥。该密钥仅显示一次。

API密钥以SHA-256哈希值的形式存储在服务器上：其原始值从未被存储，也无法还原。旧版API密钥（如`hl_live_…`）仍然有效，因为身份验证是基于哈希值而非前缀进行的。

## API密钥的有效期

创建 API 密钥时的可选过期时间：

| 选项 | 行为 |
| - | - |
| 从来没有 | API密钥在被撤销前一直有效 |
| 30 / 90 / 365天 | 该API密钥将在该期限届满后自动失效 |
| 自定义日期 | 在所选日期到期 |

过期的API密钥将被拒绝，提示如下：

```json theme={null}
{
  "status": "error",
  "error": { "code": "UNAUTHORIZED", "message": "API key sudah kedaluwarsa." }
}
```

## 每个 API 密钥的额度

每个 API 密钥均可设置 **以美元为单位的使用限额**（`creditLimit`），其重置周期为：

| 重置 | 计算窗口（UTC日历） |
| - | - |
| 日报 (`daily`) | 自当天00:00 UTC起 |
| 周刊 (`weekly`) | 自本周一协调世界时（UTC）00:00起 |
| 月刊 (`monthly`) | 自本月1日00:00（UTC）起 |
| 无需重置 | API密钥有效期内的总计 |

使用量根据该 API 密钥记录的实际请求费用（`requests.customer_cost`）进行计算。当累计费用达到限额时，后续请求将被拒绝并返回 **402 PAYMENT\_REQUIRED** 状态码：

```json theme={null}
{
  "status": "error",
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Limit kredit API key tercapai (🪙10.0000 dari 🪙10 total)."
  }
}
```

额度与**账户余额**不同：额度仅针对单个 API 密钥，而账户余额则是所有 API 密钥的资金来源。两者都必须充足，请求才能执行。请参阅 [计费与余额](https://docs.hostlinku.com/zh/billing.md)。

## 速率限制

除了额度限制外，支付网关还会针对每个API密钥实施请求频率限制：

* **[`POST /v1/chat/completions`](https://docs.hostlinku.com/zh/chat-completions)**：每个API密钥每分钟600次请求。
* 控制台/公共端点（Cookie会话）：每个IP地址每分钟120次请求。
* 身份验证端点（登录、注册、重置）：每个IP地址每15分钟限30次尝试。

超过限额将导致出现 **429 RATE\_LIMITED** 错误。详情请参阅 [使用情况与限额](https://docs.hostlinku.com/zh/usage-and-limits.md)。

## 常见的身份验证错误

| 情况 | HTTP | `error.code` | 消息 |
| - | - | - | - |
| `Authorization` 标头不存在或不是 Bearer 标头 | 401 | `UNAUTHORIZED` | `Endpoint ini memerlukan API key Hostlinku: kirim header Authorization: Bearer sk-… (atau x-api-key). …` |
| API密钥未知、输入有误或已被撤销 | 401 | `UNAUTHORIZED` | `API key tidak valid atau sudah dicabut.` |
| API密钥已过期 | 401 | `UNAUTHORIZED` | `API key sudah kedaluwarsa.` |
| API密钥用于`/api/*`控制台的端点 | 403 | `API_KEY_NOT_ALLOWED` | `API key hanya berlaku untuk endpoint gateway /v1/* …` |
| API密钥已达到额度上限 | 402 | `PAYMENT_REQUIRED` | `Limit kredit API key tercapai (…)` |
| 账户余额不足以完成预订请求 | 402 | `PAYMENT_REQUIRED` | `Saldo kredit tidak cukup untuk request ini.` |
| 超出速率限制 | 429 | `RATE_LIMITED` | `Rate limit terlampaui. …` |

API密钥的安全性

* 请勿将 API 密钥放在浏览器中运行的客户端代码或公共代码库中。- 在服务器上使用环境变量（例如 `HOSTLINKU_API_KEY`），并从中读取。 - 为每个应用程序/环境创建独立的 API 密钥，以便能够逐个撤销，而不会影响其他密钥。- 利用 **过期** 和 **额度限制** 作为防御层，以防 API 密钥泄露。 - 不再使用的 API 密钥可通过控制台进行 **撤销**（停用，历史记录仍保留）或 **清除**（永久删除）。

API密钥轮换

建议的操作流程：创建新的API密钥 → 在应用中配置 → 验证请求成功 → 撤销旧的API密钥。由于两者同时处于活跃状态，因此不会造成服务中断。


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