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

# API Key 管理

> 通过系统 API 创建、查找、显示、更新、停用、轮换和删除 API Key。

## 概述

API Key 通过 `/api/token` 下的接口管理。这些接口使用[认证与额度](/cn/api-reference/system-api/authentication-and-quota)中介绍的系统访问令牌。

<Warning>
  `PUT /api/token/` 是完整的可变配置更新，不是 JSON Merge Patch。请求中必须包含所有需要保留的设置。
</Warning>

## 可变字段

| 字段                     | 类型             | 说明                                  |
| ---------------------- | -------------- | ----------------------------------- |
| `id`                   | integer        | 更新时必填                               |
| `name`                 | string         | 显示名称，最多 50 个字符                      |
| `expired_time`         | integer        | Unix 秒级时间戳；`-1` 表示永不过期              |
| `remain_quota`         | integer        | 以内部单位表示的剩余额度                        |
| `unlimited_quota`      | boolean        | 为 `true` 时取消 Key 级额度上限              |
| `model_limits_enabled` | boolean        | 是否启用模型白名单                           |
| `model_limits`         | string         | 以逗号分隔的模型 ID                         |
| `allow_ips`            | string or null | 以换行分隔的 IP 或 CIDR；空字符串或 `null` 表示不限制 |
| `group`                | string         | 路由与计费分组                             |
| `cross_group_retry`    | boolean        | 跨分组重试，仅对受支持的自动分组有效                  |
| `smart_routing`        | boolean        | 是否为智能路由 Key                         |
| `smart_route_tiers`    | string         | JSON 字符串形式的智能路由层级配置                 |

## 创建普通 API Key

```bash theme={null}
curl -fsS -X POST "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deployment",
    "expired_time": -1,
    "remain_quota": 0,
    "unlimited_quota": true,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": "",
    "group": "default",
    "cross_group_retry": false,
    "smart_routing": false,
    "smart_route_tiers": ""
  }' | jq
```

创建成功的响应不会返回记录 ID。请使用唯一名称创建，再通过列表或搜索接口定位新记录。

## 列表与搜索

普通 Key 列表默认排除智能路由 Key：

```bash theme={null}
curl -fsS "$BASE_URL/api/token/?p=1&size=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq
```

设置 `exclude_smart_routing=false` 可包含所有 Key：

```bash theme={null}
curl -fsS "$BASE_URL/api/token/?p=1&size=20&exclude_smart_routing=false" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq
```

分页大小参数支持 `size`、`page_size` 和 `ps`，每页最多 100 条。

按名称或已存储的 Key 值搜索：

```bash theme={null}
curl -fsS --get "$BASE_URL/api/token/search" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "keyword=ci-deployment" \
  --data-urlencode "p=1" \
  --data-urlencode "size=20" | jq
```

可选的 `token` 查询参数支持带或不带 `sk-` 前缀的 Key。列表、搜索和单条读取响应中的 Key 始终经过掩码处理。

## 读取与显示完整 Key

读取掩码记录：

```bash theme={null}
curl -fsS "$BASE_URL/api/token/42" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq
```

显示完整存储值：

```bash theme={null}
stored_key=$(curl -fsS -X POST "$BASE_URL/api/token/42/key" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  | jq -er '.data.key')

api_key="sk-${stored_key#sk-}"
```

显示接口返回的存储值不会自动添加 `sk-`。请把响应直接写入密钥管理系统，不要打印到日志。

一次最多显示 100 个 Key：

```bash theme={null}
curl -fsS -X POST "$BASE_URL/api/token/batch/keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"ids":[42,43]}'
```

## 安全更新 Key

先读取当前记录，构造完整的可变字段请求体，然后只修改目标字段：

```bash theme={null}
current=$(curl -fsS "$BASE_URL/api/token/42" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

payload=$(jq '.data | {
  id,
  name,
  expired_time,
  remain_quota,
  unlimited_quota,
  model_limits_enabled,
  model_limits,
  allow_ips,
  group,
  cross_group_retry,
  smart_routing,
  smart_route_tiers
} | .name = "ci-deployment-v2"' <<< "$current")

curl -fsS -X PUT "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "$payload" | jq
```

该读取、修改、写回流程可以保留模型限制和智能路由配置。

## 启用或停用

仅更新状态不会替换其他设置：

```bash theme={null}
curl -fsS -X PUT "$BASE_URL/api/token/?status_only=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"id":42,"status":2}' | jq
```

| 状态  | 含义    |
| --- | ----- |
| `1` | 已启用   |
| `2` | 手动停用  |
| `3` | 已过期   |
| `4` | 额度已耗尽 |

过期或额度耗尽的 Key 必须先修正过期时间或额度，之后才能重新启用。

## 删除 Key

删除一个 Key：

```bash theme={null}
curl -fsS -X DELETE "$BASE_URL/api/token/42" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq
```

批量删除当前账号拥有的 Key：

```bash theme={null}
curl -fsS -X POST "$BASE_URL/api/token/batch" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"ids":[42,43]}' | jq
```

批量响应的 `data` 是实际删除的记录数量。

## 完整生命周期脚本

以下脚本创建一个有效期为一小时、使用美元金额换算额度的 Key，然后完成定位、读取完整 Key、更新、停用和删除。脚本不会把完整 Key 打印到标准输出。

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

: "${BASE_URL:=https://api.mixroute.ai}"
: "${ACCESS_TOKEN:?Set ACCESS_TOKEN}"
: "${USER_ID:?Set USER_ID}"

auth=(
  -H "Authorization: Bearer $ACCESS_TOKEN"
  -H "New-Api-User: $USER_ID"
)

name="automation-$(date +%s)-$RANDOM"
token_id=""

delete_token() {
  local response
  response=$(curl -fsS -X DELETE "$BASE_URL/api/token/$token_id" \
    "${auth[@]}")
  jq -e '.success == true' <<< "$response" >/dev/null
}

cleanup() {
  if [[ -n "$token_id" ]]; then
    delete_token >/dev/null 2>&1 || true
  fi
}
trap cleanup EXIT

quota_per_unit=$(curl -fsS "$BASE_URL/api/status" | jq -er '.data.quota_per_unit')
expires_at=$(( $(date +%s) + 3600 ))
quota=$(( 5 * quota_per_unit ))

create_payload=$(jq -n \
  --arg name "$name" \
  --argjson expires "$expires_at" \
  --argjson quota "$quota" '{
    name: $name,
    expired_time: $expires,
    remain_quota: $quota,
    unlimited_quota: false,
    model_limits_enabled: false,
    model_limits: "",
    allow_ips: "",
    group: "default",
    cross_group_retry: false,
    smart_routing: false,
    smart_route_tiers: ""
  }')

created=$(curl -fsS -X POST "$BASE_URL/api/token/" \
  "${auth[@]}" -H "Content-Type: application/json" \
  -d "$create_payload")
jq -e '.success == true' <<< "$created" >/dev/null

found=$(curl -fsS --get "$BASE_URL/api/token/search" \
  "${auth[@]}" --data-urlencode "keyword=$name" \
  --data-urlencode "p=1" --data-urlencode "size=10")
token_id=$(jq -er --arg name "$name" '
  [.data.items[] | select(.name == $name)]
  | if length == 1 then .[0].id
    else error("expected exactly one matching API key")
    end
' <<< "$found")

stored_key=$(curl -fsS -X POST "$BASE_URL/api/token/$token_id/key" \
  "${auth[@]}" | jq -er '.data.key')
api_key="sk-${stored_key#sk-}"
# 将下一行空操作替换为密钥管理系统命令。
: "$api_key"
unset stored_key api_key

current=$(curl -fsS "$BASE_URL/api/token/$token_id" "${auth[@]}")
update_payload=$(jq --argjson quota "$((10 * quota_per_unit))" '.data | {
  id, name, expired_time, remain_quota, unlimited_quota,
  model_limits_enabled, model_limits, allow_ips, group,
  cross_group_retry, smart_routing, smart_route_tiers
} | .remain_quota = $quota' <<< "$current")

curl -fsS -X PUT "$BASE_URL/api/token/" \
  "${auth[@]}" -H "Content-Type: application/json" \
  -d "$update_payload" | jq -e '.success == true' >/dev/null

curl -fsS -X PUT "$BASE_URL/api/token/?status_only=true" \
  "${auth[@]}" -H "Content-Type: application/json" \
  -d "{\"id\":$token_id,\"status\":2}" \
  | jq -e '.success == true' >/dev/null

delete_token
token_id=""
trap - EXIT
echo "API key lifecycle completed"
```