调用方 API Key

调用方 API Key 用于标识向 AISIX 代理 API 发送请求的应用。AISIX 可以使用每把 Key 限制模型访问，并应用调用方专属的流量控制。这些 Key 不授予运维人员访问权限。AISIX Cloud 运维人员通过已登录的控制台会话管理资源，或使用 Admin Token 调用 Admin API。开源 AISIX 网关的运维人员则通过资源文件或 etcd 配置网关。

本指南将介绍如何创建调用方 API Key、授予它一个或多个模型别名的访问权限，并管理其生命周期。应用会向 AISIX 发送明文调用方 API Key，而 AISIX 只在 API Key 资源中保存其 SHA-256 哈希。

本指南适用于提交明文 Key 的应用。如需让应用提交来自外部身份提供商的短期凭证，请改为配置 JWT 身份认证。AISIX 会把验证后的 JWT 身份映射到调用方 API Key，因此仍会应用该 Key 的访问控制和流量控制。在 AISIX Cloud 中，匹配的预算也会生效。

示例涵盖两种管理路径。AISIX Cloud 可以生成明文值，而开源 AISIX 网关会从环境变量派生哈希，或接受资源文件中预先计算的哈希。

准备工作

请先准备以下内容：

• 调用方应被允许使用的模型别名。如果尚未创建，请先配置服务提供方密钥和模型别名。
• 对于 AISIX Cloud，需要环境访问权限和具备写入权限的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
• 对于开源 AISIX 网关，需要包含该模型别名的声明式资源文件。

创建调用方 API Key

根据部署的管理路径配置调用方凭证。

AISIX Cloud

导出 AISIX Cloud 连接信息，以及调用方可使用的模型 ID：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export MODEL_ID="YOUR_MODEL_ID"

MODEL_ID 是创建模型别名时返回的 id，不是别名。

使用允许的模型创建 API Key 资源。AISIX Cloud 会生成明文密钥，并且只在创建响应中返回一次：

RESPONSE=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "chat-app",
    "allowed_models": ["'"$MODEL_ID"'"]
  }')

export API_KEY_ID=$(echo "$RESPONSE" | jq -r '.api_key.id')
export AISIX_API_KEY=$(echo "$RESPONSE" | jq -r '.plaintext')
echo "$RESPONSE" | jq

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

{
  "api_key": {
    "id": "f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387",
    "env_id": "9be9891a-6a53-4bd8-a897-a03fe38a1ca5",
    "display_name": "chat-app",
    "allowed_models": [
      "6a3f2c1d-8f4e-49b2-b6f1-3f6f24d0f9a2"
    ],
    "disabled": false,
    "status": "active",
    "created_at": "2026-06-24T12:18:39Z",
    "updated_at": "2026-06-24T12:18:39Z"
  },
  "plaintext": "sk-***"
}

高亮的 id 用于以后更新、轮换或删除该密钥。高亮的 plaintext 是调用方凭证。它只在此响应中返回且以后无法恢复，因此请安全保存，并立即使用它配置应用。该密钥会自动投射到已关联的网关。

开源 AISIX 网关

选择明文调用方凭证，并使其可用于网关进程：

export CALLER_API_KEY="YOUR_CALLER_API_KEY"

向 api_keys 集合添加条目。key_env 值是环境变量的名称，不是凭证本身：

resources.yaml（调用方 API Key）

api_keys:
  - display_name: chat-app
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod

网关通过模型的 display_name 解析 allowed_models，并将环境变量值的 SHA-256 哈希存储在活动资源中。应用前请验证完整的资源文件。如果 CALLER_API_KEY 已可用于运行中的网关进程，请发送 SIGHUP 重新加载文件。如果现在才引入该变量，请使用该变量重启或重新创建网关，以便进程能够解析它。

控制模型访问

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

访问模式	AISIX Cloud	开源 AISIX 网关	适用场景
指定模型	列出同一环境中的模型资源 ID，例如 ["$MODEL_ID"]。	列出同一资源文件中的模型别名，例如 ["gpt-4o-prod"]。也支持单个 * 的 Glob 模式。	应用只应调用已批准的模型别名。
不授予模型访问权限	使用 []。	使用 []。	需要先创建密钥，之后再授予模型访问权限。

模型列表端点也使用同一个允许列表。它会返回调用方 API Key 可访问的所有具体直接或虚拟别名，包括路由、语义和合议别名。通配符别名是模式而非具体模型名称，因此不会返回。

验证访问

导出网关 Origin：

# AISIX_PROXY 是网关源站；请勿包含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

AISIX Cloud 创建示例已经将生成的明文保存到 AISIX_API_KEY。对于开源 AISIX 网关，请使用赋给 CALLER_API_KEY 的明文值：

# 仅适用于开源 AISIX 网关。
export AISIX_API_KEY="$CALLER_API_KEY"

调用方发送模型别名和明文密钥：

curl -sS -X POST "$AISIX_PROXY/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，请检查应用是否使用了明文密钥，以及请求的模型别名是否被允许。

列出调用方可见的模型，确认已配置的别名出现：

curl -sS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

从其他网关导入已有密钥

从其他 AI 网关迁移时，可以导入现有调用方 API Key，让应用迁移到 AISIX 后继续使用同一凭证。AISIX 认证请求时会对传入的 Bearer Token 计算哈希，因此现有密钥值不需要 AISIX 专用前缀、长度或字符集。

在 AISIX Cloud 中，通过 key 字段提供现有明文值，而不是让控制面生成：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "imported-caller",
    "allowed_models": ["'"$MODEL_ID"'"],
    "key": "YOUR_EXISTING_CALLER_KEY"
  }'

批量导入 AISIX Cloud 时，请对每个密钥重复相同请求。使用相同 display_name 再次运行导入会返回 409（名称重复），因此导入可以安全重试。系统不会检查密钥值是否重复，所以请在重试之间保持显示名称稳定。

对于开源 AISIX 网关，请在启动网关前，将 key_env 指定的环境变量设置为现有明文值。要避免向网关进程提供明文，请在资源文件中将 key_hash 设置为小写 SHA-256 十六进制哈希。每个调用方 API Key 必须且只能配置 key_env 或 key_hash 之一。

设置过期时间

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

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

AISIX Cloud

创建时设置过期时间：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "expiring-caller",
    "allowed_models": ["'"$MODEL_ID"'"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

如需修改现有密钥的截止时间，请使用 PATCH 更新。此次更新只会更改发送的字段：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2027-06-30T00:00:00Z"
  }'

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

如需让密钥重新永久有效，请发送 "expires_at": null 清除截止时间。

开源 AISIX 网关

在调用方 API Key 条目上设置截止时间：

resources.yaml（API Key 过期时间）

api_keys:
  - display_name: chat-app
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod
    expires_at: "2027-01-01T00:00:00Z"

验证并重新加载资源文件，以添加、更改或移除截止时间。加载后，网关会在每次请求时检查截止时间。

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

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

AISIX Cloud

使用 PATCH 更新暂停访问：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "disabled": true
  }'

如需重新启用密钥，请发送同一请求并将 disabled 设置为 false。其他字段（例如模型允许列表和所有限制）不会被此次更新改变。

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

开源 AISIX 网关

在调用方 API Key 条目上设置 disabled: true，然后验证并重新加载资源文件：

resources.yaml（已禁用的 API Key）

api_keys:
  - display_name: chat-app
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod
    disabled: true

将 disabled 设置为 false 或移除该字段，再重新加载文件，即可使用相同凭证恢复访问。

轮换调用方 API Key

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

AISIX Cloud

轮换 API Key 资源。该请求没有请求体：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID/rotate" \
  -H "Authorization: Bearer $AISIX_TOKEN"

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

{
  "api_key": {
    "id": "f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387",
    "env_id": "9be9891a-6a53-4bd8-a897-a03fe38a1ca5",
    "display_name": "chat-app",
    "allowed_models": [
      "6a3f2c1d-8f4e-49b2-b6f1-3f6f24d0f9a2"
    ],
    "disabled": false,
    "status": "active",
    "created_at": "2026-06-24T12:18:39Z",
    "updated_at": "2026-06-24T12:21:05Z"
  },
  "plaintext": "sk-***"
}

轮换只会替换凭证。密钥资源会保留：名称、模型允许列表、限流、绑定、过期截止时间和禁用状态都会延续。高亮的新明文只会在轮换响应中返回一次。请安全保存并更新应用；轮换后的资源到达网关时，旧明文将无法继续认证。

AISIX 控制台的 API keys 页面提供相同的生命周期操作。页面会显示密钥是 Active、Expired 还是 Disabled，并且会在轮换期间只显示一次新明文值。每次生命周期变更都会记录到组织审计日志中。

开源 AISIX 网关

如需立即切换，请替换通过 key_env 提供的值并重启网关，使进程收到新的环境变量值。替换后的配置加载时，旧明文将停止工作。

如需渐进轮换，请让两个凭证均可用，并将 chat-app-new 添加到 api_keys。轮换期间保持 chat-app 不变：

resources.yaml（替换用 API Key）

api_keys:
  - display_name: chat-app-new
    key_env: NEW_CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod

如果新环境变量尚不可用于网关进程，请重启或重新创建网关。在两个凭证都能工作后，更新应用以使用新值，移除旧条目，然后验证并重新加载资源文件。此流程可以在调用方迁移期间继续使用旧凭证。

替换项是一个独立的调用方 API Key。请复制所有应继续生效的访问、生命周期、归因和内联限流字段，包括已配置的 mcp_access、allowed_agents、expires_at、team_id、user_id、user_name 和 rate_limit。对于每个 scope: api_key 且 scope_ref: chat-app 的 rate_limit_policies 条目，请在重叠期间添加对应策略，使用唯一名称并设置 scope_ref: chat-app-new。只有在应用停止使用旧密钥后，才移除旧策略。

下一步

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

如果要将调用方凭证绑定到团队以进行归因和共享控制，请参阅团队。如果要添加面向调用方的限制或共享策略控制，请参见 API Key 与模型限流、限流策略和预算。