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

# BYOK

> 自带密钥（Bring Your Own Key）——注册上游提供商凭据，让 VibeToken 使用你的账户代表你调用 OpenAI / Anthropic / Google。

**BYOK**（自带密钥，Bring Your Own Key）让你为受支持的提供商（OpenAI、Anthropic、Google）注册自己的上游凭据。注册之后，VibeToken 会在每个经该提供商路由的请求中使用它——费用直接计入你的上游账户；VibeToken 绝不会对 BYOK 调用向你收费。

**这是数据，而非调用方令牌。** 你永远不会在 `Authorization` 请求头中向 VibeToken 出示 BYOK 凭据。你只需通过下面的端点注册一次；VibeToken 会在请求时静默地使用它。

**这些端点的鉴权方式：** JWT（已登录的控制台会话）或 API Key。

## 运行时行为

当对 `/v1/chat/completions`（或图像 / 视频 / 音频）的调用解析到某个你已配置 BYOK 凭据的提供商时：

1. 候选项按 `priority DESC, created_at DESC` 排序。`disabled=true` 的行会被排除。
2. 每个候选项尝试一次。成功时 `last_used_at` 前移，`last_error` 清空。
3. 失败时记录 `last_error`，并尝试下一个候选项。
4. 若没有任何候选项成功：
   * 如果该提供商下你的**任意一行**设置了 `always_use=true` → 返回上游错误。不会回退到平台密钥。
   * 否则 → VibeToken 会回退到它针对该提供商的平台凭据。

## 列出提供商密钥

```
GET https://vibetoken.cn/api/v1/byok
```

### 查询参数

<ParamField query="provider" type="string">
  筛选到单个提供商：`openai`、`anthropic` 或 `google`。
</ParamField>

### 响应

```json theme={null}
[
  {
    "id": "01J...",
    "provider": "openai",
    "label": "My OpenAI (prod)",
    "api_key_prefix": "sk-proj-…",
    "base_url": null,
    "config_json": null,
    "always_use": false,
    "disabled": false,
    "priority": 0,
    "last_used_at": "2026-04-23T12:00:00Z",
    "last_error": null,
    "created_at": "2026-04-22T09:00:00Z",
    "updated_at": "2026-04-23T12:00:00Z"
  }
]
```

明文的 `api_key` 永远不会被返回。`config_json` 中的敏感字段（`secretAccessKey`、`private_key`、`api_key`、`token` 等）会被掩码为 `"***"`。

***

## 创建提供商密钥

```
POST https://vibetoken.cn/api/v1/byok
```

### 请求体

<ParamField body="provider" type="string" required>
  `openai`、`anthropic`、`google` 之一。
</ParamField>

<ParamField body="label" type="string" required>
  1–100 个字符。面向用户的名称，例如 "Personal OpenAI (prod)"。
</ParamField>

<ParamField body="api_key" type="string">
  上游凭据。除非由 `config_json` 携带（例如 Vertex 服务账户 JSON），否则必填。
</ParamField>

<ParamField body="base_url" type="string">
  可选，覆盖上游的 base URL。必须为 HTTPS。
</ParamField>

<ParamField body="config_json" type="object">
  提供商特定的额外配置（例如 Azure `{endpoint_url, deployment_id}`、Bedrock `{region, …}`、Vertex 服务账户 JSON + `region`）。此对象内的密钥字段会在所有读取响应中被掩码。
</ParamField>

<ParamField body="always_use" type="boolean" default="false">
  设为 `true` 时，若该提供商的每个 BYOK 候选项都失败，则禁用平台密钥回退。
</ParamField>

<ParamField body="priority" type="number" default="0">
  限定在 `[-1000, 1000]` 范围内。当同一 `(user, provider)` 存在多行时，值更高者胜出。相同时按 `created_at DESC` 决定。
</ParamField>

### 示例

```bash theme={null}
curl -X POST https://vibetoken.cn/api/v1/byok \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "label": "My OpenAI (prod)",
    "api_key": "sk-proj-xxxxxxxxxxxx",
    "always_use": true
  }'
```

***

## 更新提供商密钥

```
PUT https://vibetoken.cn/api/v1/byok/{id}
```

以下任意子集：

<ParamField body="label" type="string" />

<ParamField body="api_key" type="string" />

<ParamField body="base_url" type="string" />

<ParamField body="config_json" type="object" />

<ParamField body="always_use" type="boolean" />

<ParamField body="disabled" type="boolean">
  暂停凭据而不删除它。`true` 会将其从候选列表中排除。
</ParamField>

<ParamField body="priority" type="number" />

***

## 删除提供商密钥

```
DELETE https://vibetoken.cn/api/v1/byok/{id}
```

返回 `204`。对该提供商的下一次推理调用会跳过已删除的行。

***

## 轮换凭据

安全的做法是**先增后删**：

```bash theme={null}
# 1. Add the new credential (will be tried first due to higher created_at)
curl -X POST .../byok -d '{"provider":"openai","label":"prod-2026-04","api_key":"sk-proj-NEW"}'

# 2. Verify by making a normal /v1/chat/completions call — check `last_used_at` on the new row

# 3. Delete the old credential
curl -X DELETE .../byok/<old-id>
```