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

# 密钥

> VibeToken 提供三种密钥。请根据你的使用场景选择合适的一种。

VibeToken 提供**三种密钥**。它们看起来相似，但用途各不相同，搞混它们是集成时最常见的错误。

## 三种密钥速览

| 类型                                | 前缀             | 持有者               | 用途                                                                 |
| --------------------------------- | -------------- | ----------------- | ------------------------------------------------------------------ |
| **API Key**                       | `sk-rb-…`      | 你的终端用户（或你自己）      | 调用模型：对话、图像、视频、音频                                                   |
| **Management API Key**            | `sk-rb-prov-…` | 你的 SaaS 后端 / 运维脚本 | 以编程方式创建、轮换和吊销 API Key —— 无法调用模型                                    |
| **BYOK**（Bring Your Own Key，自带密钥） | *不透明的上游密钥*     | 你，一次性注册           | 让 VibeToken 使用**你的**凭据（而非我们的）去调用上游提供商（OpenAI / Anthropic / Google） |

## 我需要哪一种？

> 「我只是想试用一下 VibeToken。」
> → **API Key**。在[控制台](https://vibetoken.cn/api-key)获取一个，放进 `Authorization: Bearer`，搞定。

> 「我正在 VibeToken 之上构建产品，希望为产品的每个终端用户分配一个密钥。」
> → **Management API Key**。将其保存在服务端；用它为每次注册铸造一个全新的 **API Key**。每个用户拥有各自的速率限制，且可以被独立吊销。

> 「我已经直接向 OpenAI / Anthropic / Google 付费，希望我的 VibeToken 调用计费到我现有的账户上，而不是 VibeToken 的账户。」
> → 注册一个 **BYOK 凭据**。你的 API Key 仍然用于*向* VibeToken 进行身份验证；而对该提供商的出站调用则使用你的上游凭据。

> 「三种我都想要。」
> → 支持。它们之间互不排斥。

## 它们如何协同工作

```
                                                       ┌──────────────┐
                                                       │   Upstream   │
                                                       │   Provider   │
                                                       │ (OpenAI,     │
                                                       │  Anthropic,  │
                                                       │  Google)     │
                                                       └──────▲───────┘
                                                              │
                                   platform key (ours)        │
                                   ─────── OR ───────         │
                                   BYOK (your key, stored     │
                                   once)                      │
                                                              │
  ┌──────────────┐ sk-rb-prov-…    ┌────────────────────┐     │
  │  Your SaaS   │                 │   VibeToken       │     │
  │  backend /   │ ──────────────▶ │                    │     │
  │  ops scripts │ CRUDs API keys  │  /api/v1/keys      │     │
  └──────────────┘                 │                    │     │
                                   │                    │     │
  ┌──────────────┐ sk-rb-…         │  /v1/chat/…        │     │
  │  End user    │                 │  /v1/images/…      │─────┘
  │  (or you)    │ ──────────────▶ │  /v1/videos/…      │
  └──────────────┘ calls models    │  /v1/audio/…       │
                                   └────────────────────┘
```

* **指向** VibeToken 的箭头 —— 你的 **API Key** 或 **Management API Key**。两者都位于 `Authorization` 头中，只是前缀不同。
* **从** VibeToken **指出**的箭头 —— 你的 **BYOK 凭据**。它绝不会出现在发往 VibeToken 的 `Authorization` 头中；只需一次性存储，当 VibeToken 代表你调用上游提供商时用于出站请求。

## 严格隔离

中间件会对用在错误路由上的错误密钥类型返回 `403`：

* 在 `/v1/chat/completions`（或任何补全 / 媒体路由）上使用 **Management API Key** → `403` "Management keys cannot call completion endpoints"。没有任何绕过方式。
* 在 `/api/v1/keys`（供 Management Key 使用的 CRUD 端点）上使用 **API Key** → `403`。

## 使用你的 API Key

在每个请求中将其作为 Bearer 令牌包含进去：

```http theme={null}
Authorization: Bearer sk-rb-xxxxxxxxxxxx
Content-Type: application/json
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://vibetoken.cn/v1/chat/completions \
    -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepseek/deepseek-v4-pro",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-rb-xxxxxxxxxxxx",
      base_url="https://vibetoken.cn/v1",
  )

  resp = client.chat.completions.create(
      model="google/gemini-2.5-flash",
      messages=[{"role": "user", "content": "Hello"}],
  )
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "sk-rb-xxxxxxxxxxxx",
    baseURL: "https://vibetoken.cn/v1",
  });

  const resp = await client.chat.completions.create({
    model: "google/gemini-2.5-flash",
    messages: [{ role: "user", content: "Hello" }],
  });
  ```
</CodeGroup>

每个密钥仅在创建时**显示一次** —— 请立即复制。完整 CRUD：[API Keys 参考](/api-reference/api-keys)。

## 使用 Management API Key

通过已登录的控制台铸造一个（以 JWT 认证作为信任根 —— Management Key 无法铸造其他 Management Key）。然后在服务端用它为你的终端用户创建 API Key：

```bash theme={null}
curl -X POST https://vibetoken.cn/api/v1/keys \
  -H "Authorization: Bearer sk-rb-prov-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "user_12345 production key", "rate_limit_rpm": 60}'
# → returns the plaintext API key once; hand it to your end user
```

## 安全

<Warning>
  * 切勿将这些密钥中的任何一个嵌入前端代码、浏览器 JavaScript 或移动应用中。
  * 切勿与终端用户分享 **Management API Key** —— 它可以铸造和吊销你整个账户上的密钥。
  * 切勿分享 **BYOK 凭据** —— 它会向你的上游提供商账户计费。
</Warning>

* 将密钥存储在环境变量或密钥管理器（AWS Secrets Manager、Vault 等）中。
* 使用 IP 白名单将 API Key 限制在你的服务器 IP 上。
* 定期轮换密钥。`disabled=true` 会暂停；`DELETE` 会永久吊销。