调用方 API Key

本指南将介绍如何创建调用方 API Key、允许它使用一个或多个模型别名，并配置其生命周期。

调用方 API Key 用于在代理 API 上认证应用。它们与管理请求使用的 Admin Key 相互独立。应用会向 AISIX 发送明文调用方 API Key，而 AISIX 只在 API Key 资源中保存 SHA-256 哈希。

准备工作

请先准备以下内容：

一个 Admin 和代理监听器都可用的自托管网关。
网关 config.yaml 中的 Admin Key。
调用方应被允许使用的模型别名。如果还没有创建，请先配置服务提供方凭证和模型别名。

创建调用方 API Key

选择应用要发送给 AISIX 的明文密钥。在创建 Admin 资源前，先计算它的哈希：

# 请替换为实际值
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

使用该哈希以及此调用方 API Key 可使用的模型别名创建 API Key 资源：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "key_hash": "${AISIX_API_KEY_HASH}",
    "allowed_models": ["gpt-4o-prod"]
  }
EOF

你应该会看到类似下面的响应：

{
  "id": "f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387",
  "value": {
    "key_hash": "43d758e3b4aa2aacdb4b49c09c26435fb5083148fda6cfc9c5e38078915c6bdb",
    "allowed_models": [
      "gpt-4o-prod"
    ]
  },
  "revision": 1
}

如果后续需要更新、轮换或删除该调用方 API Key，请复制高亮的 id。

请在应用中配置明文密钥。保存的 key_hash 不是可用的调用方凭证。

控制模型访问

模型允许列表是调用方 API Key 的授权边界。请选择与该 API Key 用法匹配的最小范围。

访问模式	`allowed_models` 值	适用场景
指定别名	`["gpt-4o-prod", "chat-prod"]`	大多数应用只应调用已批准的模型别名。
所有可见模型	`["*"]`	可信内部 API Key 需要较宽的模型访问权限。
不授予模型访问	`[]`	需要先创建 API Key，后续再授予模型访问权限。

模型列表端点也使用同一个允许列表。它会返回调用方 API Key 可访问的单目标、合议和语义路由器模型。多目标路由别名在被允许时可以调用，但不会包含在模型列表中。

验证访问

向允许访问的模型别名发送请求。调用方使用的是明文密钥，而不是哈希：

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "messages": [
      {"role": "user", "content": "Hello from AISIX."}
    ]
  }'

成功的请求会到达上游模型，并返回 Chat Completions 响应。如果代理返回 401 或 403，请检查应用是否使用了明文密钥，以及请求的模型别名是否被允许。

从其他网关导入已有 Key

如果你正从其它 AI 网关迁移，可以导入现有调用方 API Key，让应用迁移到 AISIX 后继续使用同一凭证。在自托管 AISIX 中，请根据现有明文 Key 的 SHA-256 哈希创建每个 API Key 资源。AISIX 认证请求时会对传入 Bearer Token 计算哈希，因此现有 Key 不需要 AISIX 专属前缀、长度或字符集。

导入时，请将现有密钥作为上文创建调用方 API Key 流程中的明文值。先计算它的哈希，再使用该 key_hash 和该密钥应访问的模型别名创建 API Key 资源。批量迁移时，可以对每个密钥重复同一请求。由于 key_hash 唯一，重复导入已存在的密钥会返回冲突，因此迁移过程可以安全重试。

在 AISIX 托管控制面中，无需自行计算导入 Key 的哈希。创建 API Key 时提供现有 Key 作为自定义值，AISIX 会保存其哈希。管理员可以控制是否允许自定义 API Key 值。关闭自定义值后，所有 Key 都必须由系统自动生成。

设置过期时间

默认情况下，调用方 API Key 永不过期。当密钥应在某个截止时间后停止工作时，请将 expires_at 设置为 RFC 3339 时间戳。

截止时间到达后，代理会以 401 拒绝该密钥，并返回错误码 api_key_expired。AISIX 会在每次请求时检查过期时间，因此无需重启或修改配置，密钥也会在截止时间后失效。

创建密钥时设置过期时间：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "key_hash": "${AISIX_API_KEY_HASH}",
    "allowed_models": ["gpt-4o-prod"],
    "expires_at": "2027-01-01T00:00:00Z"
  }
EOF

如需修改已有密钥的截止时间，请使用 PUT 更新。发送完整 API Key 资源，并只改变 expires_at 值：

export API_KEY_ID="f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387"

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/${API_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "key_hash": "${AISIX_API_KEY_HASH}",
    "allowed_models": ["gpt-4o-prod"],
    "expires_at": "2027-06-30T00:00:00Z"
  }
EOF

设置未来的过期时间不会影响截止时间前的使用。带有未来 expires_at 的密钥仍会正常认证。

如需让密钥重新永久有效，请发送完整 PUT 更新并省略 expires_at。由于 PUT 会替换资源，请包含所有需要保留的字段，例如 key_hash、allowed_models、rate_limit 或 allowed_tools。

禁用和重新启用调用方 API Key

禁用可以在不删除密钥的情况下暂停访问。代理会以 401 拒绝已禁用密钥，并返回错误码 api_key_disabled。密钥值本身会保留，重新启用后应用持有的同一凭证会恢复可用。

使用完整资源更新暂停访问：

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/${API_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "key_hash": "${AISIX_API_KEY_HASH}",
    "allowed_models": ["gpt-4o-prod"],
    "disabled": true
  }
EOF

如需重新启用密钥，请发送同一请求并将 disabled 设置为 false，或省略该字段。由于 PUT 会替换资源，请在请求体中保留模型允许列表和任何限制配置。

当调用方之后还可能恢复访问时，可以使用禁用处理应急响应或临时暂停访问。如果明文密钥可能泄露，请使用轮换；如果调用方已永久下线，则删除该密钥。

轮换调用方 API Key

当已有调用方 API Key 需要新的明文值时，可以执行密钥轮换。

将 API_KEY_ID 设置为创建响应中高亮的 id，然后轮换 API Key 资源：

export API_KEY_ID="f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys/${API_KEY_ID}/rotate" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

你应该会看到类似下面的响应：

{
  "entry": {
    "id": "f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387",
    "value": {
      "key_hash": "4c79f2cc907407e8218346d28c64eb4e8ed4db2a50ea74e75f3a8f5c4f4d0f20",
      "allowed_models": [
        "gpt-4o-prod"
      ]
    },
    "revision": 2
  },
  "plaintext": "sk-***"
}

轮换响应是 AISIX 唯一一次返回高亮明文密钥的时机。请安全保存它，并更新应用以使用新值。后续读取只会返回哈希。

如果使用 AISIX 托管控制面，API keys 页面提供相同的生命周期操作。页面会显示 Key 是 Active、Expired 还是 Disabled。你可以在同一页面设置或清除过期时间、禁用或重新启用 Key，并轮换 Key。AISIX 只会在轮换时展示一次新的明文值。

对于 API 自动化，AISIX Cloud Admin API 在 PATCH 上接受相同的生命周期字段。发送 "expires_at": null 可以清除截止时间。每次生命周期变更都会记录到组织审计日志中。

下一步

你已经配置了调用方如何认证以及它可以使用哪些模型别名。当一个模型别名需要从多个上游目标中选择时，请继续阅读路由与故障转移。

如果要添加面向调用方的限制或共享策略控制，请参见限流和预算。

准备工作​

创建调用方 API Key​

控制模型访问​

验证访问​

从其他网关导入已有 Key​

设置过期时间​

禁用和重新启用调用方 API Key​

轮换调用方 API Key​

下一步​