调用方 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="admin-local-only-change-me"
export AISIX_API_KEY="sk-app-caller"
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" \
-d '{
"key_hash": "'"${AISIX_API_KEY_HASH}"'",
"allowed_models": ["gpt-4o-prod"]
}'
你应该会看到类似下面的响应：
{
"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，请检查应用是否使用了明文密钥，以及请求的模型别名是否被允许。
轮换调用方 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 唯一一次返回高亮明文密钥的时机。请安全保存它，并更新应用以使用新值。后续读取只会返回哈希。
下一步
你已经配置了调用方如何认证以及它可以使用哪些模型别名。当一个模型别名需要从多个上游目标中选择时，请继续阅读路由与故障转移。