版本：1.8.0

调用方 API Key

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

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

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

示例涵盖 AISIX Enterprise 和 AISIX Cloud 使用 AISIX Cloud Admin API 的路径，以及 AISIX OSS 使用资源文件的路径。API 可以生成明文值，而开源 AISIX 网关会从环境变量派生哈希，或接受资源文件中预先计算的哈希。

准备工作

请先准备以下内容：

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

创建调用方 API Key

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

AISIX Enterprise 或 AISIX Cloud

导出控制面连接信息，以及调用方可使用的模型 ID：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_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 Admin API 会生成明文密钥，并且只在创建响应中返回一次：

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

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

验证访问

导出网关源地址：

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

控制面创建示例已经将生成的明文保存到 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 Enterprise 和 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"
  }'

密钥值在其环境内必须唯一。使用同一环境中其他密钥已在使用的值创建密钥，会返回 409，错误码为 DUPLICATE_NAME。同一个值可以在不同环境中使用，因此一个密钥可以导入到承载其流量的每个环境。

默认允许使用自定义密钥值。组织可以关闭它：打开 Settings，在 API key import 卡片中取消勾选 Allow custom API key values。该设置作用于组织的所有环境。所有者和管理员可以修改它，对组织拥有写权限的自定义角色也可以。关闭期间，携带 key 的创建请求会被拒绝，返回 403，错误码为 CUSTOM_KEY_DISABLED，每个新密钥都会使用自动生成的值。关闭只影响新密钥：已经以自定义值创建的密钥仍可在网关上正常使用。

批量向控制面导入时，请对每个密钥重复相同请求。向同一环境再次运行导入会返回 409，错误码为 DUPLICATE_NAME，因为该环境中的 display_name 或密钥值已被占用，所以导入可以安全重试。

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

如需将控制面的调用方 Key 归属到组织成员，请将其 user_id 设置为成员 API 返回的成员资格 id。成员账号的 user_id 是另一个标识符。绑定团队不能代替成员归属。

设置过期时间

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

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

AISIX Enterprise 或 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 Enterprise 或 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。其他字段（例如模型允许列表和所有限制）不会被此次更新改变。如果密钥的所有者已被 SCIM 目录同步停用，重新启用会返回 400；请在同一请求中把密钥绑定到一个活跃成员，或移除它的 user_id。

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

开源 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 Enterprise 或 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 设置标签

在 AISIX Enterprise 和 AISIX Cloud 中，调用方 API Key 可以带有成本归属标签，例如 department=rnd。可以在 Key 的创建或编辑表单的 Cost-attribution tags 部分设置，也可以在 POST /environments/{environment_id}/api_keys 和 PATCH /environments/{environment_id}/api_keys/{api_key_id} 中使用 tags。Key 自己设置的标签优先于其团队和成员上的值。详见请求如何解析标签。

下一步

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

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

准备工作​

创建调用方 API Key​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

控制模型访问​

验证访问​

从其他网关导入已有密钥​

设置过期时间​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

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

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

轮换调用方 API Key​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

为调用方 API Key 设置标签​

下一步​

准备工作

创建调用方 API Key

AISIX Enterprise 或 AISIX Cloud

开源 AISIX 网关

控制模型访问

验证访问

从其他网关导入已有密钥

设置过期时间

AISIX Enterprise 或 AISIX Cloud

开源 AISIX 网关

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

AISIX Enterprise 或 AISIX Cloud

开源 AISIX 网关

轮换调用方 API Key

AISIX Enterprise 或 AISIX Cloud

开源 AISIX 网关

为调用方 API Key 设置标签

下一步