调用方 API Key

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

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

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

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

准备工作

请先准备以下内容：

• 调用方应被允许使用的模型别名。如果尚未创建，请先配置服务提供方密钥和模型别名。
• 对于 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，且末尾不包含斜杠。
# 本地 On-Premises 快速入门使用 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_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 是网关 Origin；末尾不包含斜杠和端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

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_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_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 提供的值并重启网关，使进程收到新的环境变量值。替换后的配置加载时，旧明文将停止工作。

如需渐进轮换，请让两个凭证都可用于网关进程，并声明具有相同访问权限的第二个调用方 API Key：

resources.yaml

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

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

替换项是一个独立的调用方 API Key。请复制所有应继续生效的访问、生命周期、归因和内联限流字段，包括已配置的 allowed_tools、allowed_agents、mcp_access、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 与模型限流、限流策略和预算。