一、操作场景
为确保敏感密钥信息的安全，AI 网关与腾讯云密钥管理系统（KMS）深度集成，实现密钥的全生命周期加密存储。KMS 使用经过第三方认证的硬件安全模块（HSM）来生成和保护密钥，确保包括腾讯云在内的任何人都无法获取你的明文主密钥，满足严格的合规性要求。通过集中化管理，本功能旨在强化安全管控，杜绝明文泄露和未授权访问风险，同时简化密钥的创建、更新、禁用、删除等运维流程。
创建密钥并将密钥绑定至消费者后（单个消费者支持绑定多种类型的密钥，一个密钥最多绑定给一个消费者），还需在模型 API 或 MCP 服务上配置相应的认证策略，才能完成访问控制的完整链路。
这篇档指导你如何在 AI 网关中为消费者创建密钥（认证凭证）。除在消费者密钥页签单独新建密钥外，AI 网关还支持以下两种快捷方式：在新建消费者时自动生成并关联密钥，以及在消费者密钥页签批量为多个消费者自动生成并关联密钥，进一步提升密钥创建与分配效率。
二、前提条件
如果生成方式使用密钥管理系统（KMS 凭据）则需要创建凭据，详情请参见凭据管理系统-快速入门。
四、查看密钥列表
1. 登录 腾讯云控制台 ，在左侧导航栏选择 AI 网关 > 实例管理，进入实例列表。
2. 在实例列表页面，单击需要配置的网关实例的“ID”，进入该网关实例的基本信息页面。
3. 在左侧导航栏单击消费者管理，单击消费者密钥页签。
4. 列表页将展示所有已创建的消费者密钥，包括密钥名称、类型、状态和生成方式等信息。你可以在此进行新建、编辑或删除等操作。
5. 当密钥状态为已启用时，删除操作将置灰不可用，系统会提示“请先禁用该密钥”。
五、新建密钥
1. 在消费者密钥列表页，单击新建。
2. 在新建密钥窗口中，配置以下密钥公共基础参数：
| 参数 | 是否必填 | 说明 |
| 密钥名称 | 是 | 2-60个字符，支持中英文大小写、数字及分隔符（"-"、"_"），不能以数字和分隔符开头，不能以分隔符结尾。 |
| 密钥凭证类型 | 是 | 选择凭证类型：API Key / JWT / OAuth 2.0 / OIDC。不同类型对应的配置项不同，详见下一步操作。API Key 是最简单的认证方式，适用于内部服务或可信客户端。JWT（JSON Web Token）适用于需要传递用户身份信息的场景，由客户端自行签发 Token 并在请求中携带。OAuth 2.0 适用于需要接入第三方 OAuth 服务的场景，由客户端使用 Client ID/Secret 换取 Token 后携带访问。OIDC（OpenID Connect）是基于 OAuth 2.0 的身份认证协议，适用于需要用户身份认证的场景。 |
| 描述 | 否 | 密钥的标识描述信息，最长可输入200个字符。 |
3. 填写凭证具体配置参数
3.1 密钥凭证类型：API Key
| 参数 | 是否必填 | 说明 |
| 生成方式 | 是 | 自定义：手动输入密钥值（消费者密钥为凭证内容）。 |
| | | 密钥管理系统（KMS凭据）：关联腾讯云KMS中的凭据。需填写“凭据名称”和“凭据版本”，若无 KMS 凭证，则可以单击“新建凭证”跳转新建。 |
| | | 自动生成：网关自动生成随机的 API key。 |
| 凭证内容 | 是 | 8-60 个字符，支持英文大小写、数字及符号（"-"、"_"、"="），其中 "-"、"_" 不能作为首尾字符。 |
注意：说明：
注意：API Key 一旦生成，请妥善保管，不要泄露给无关人员。
3.2 密钥凭证类型：JWT
| 参数 | 是否必填 | 说明 |
| 算法 | 是 | 选择 JWT 签名算法，如 HS256。 |
| 共享密钥 | 是 | 填写用于签发和验证 JWT 的共享密钥。 |
| 消费者标识 | 是 | 客户端自签 JWT 时把 iss 设为该值，网关按此反查消费者。建议使用业务可读名（如组织名 / 邮箱）。 |
3.3 密钥凭证类型：OAuth 2.0
| 参数 | 是否必填 | 说明 |
| 客户端 ID | 是 | OAuth 客户端 ID。 |
| 客户端密钥 | 是 | OAuth 客户端密钥。 |
3.4 密钥凭证类型：OIDC
| 参数 | 是否必填 | 说明 |
| 客户端 ID | 是 | OIDC 客户端 ID。 |
| 客户端密钥 | 是 | OIDC 客户端密钥。 |
| 签发者地址 | 是 | 身份提供商（IdP）签发地址，用于发现 OIDC 配置，如 https://example.com/oidc。 |
| 消费者标识 Claim 值 | 是 | IdP token 中用户的 claim 值（如 sub/email），运行时用于反查对应消费者，如 user@example.com。 |
4. 完成创建：单击确定完成密钥创建。新建的密钥将展示在消费者密钥列表中。
六、批量为指定消费者生成并关联密钥
当需要为多个消费者一次性补齐消费者密钥时，可通过批量新建方式，为选中的消费者逐个自动生成 API Key 类型密钥并自动关联。
1. 在消费者密钥列表页，单击批量新建，打开批量新建密钥弹窗。
2. 在弹窗左侧筛选并勾选需要生成密钥的消费者：
·通过来源下拉框筛选消费者来源。
·通过密钥情况下拉框筛选：全部 / 未关联密钥 / 已关联密钥。
·在搜索框输入消费者名称 / ID 快速查找。
·勾选全选当前筛选结果可批量选中，单击清空选择可取消全部选择。
3. 在弹窗右侧填写密钥生成参数：
·密钥凭证类型：固定为 API Key，不可修改。
·密钥名称前缀：必填，前缀最多 50 个字符，需以字母或数字开头，仅支持字母、数字、下划线和短横线。最终密钥名称为 auto-前缀-随机后缀。
·描述：选填，默认值为“批量自动生成密钥”。
4. 单击确认生成，系统为选中的消费者逐个自动生成 API Key 类型密钥并关联。
注意：单次最多支持为 500 个消费者自动生成密钥，若超出数量请分次进行。
5. 生成过程中，弹窗展示密钥生成结果，各消费者状态为“生成中”；生成完成后，支持一键导出本批次密钥生成结果，列表按以下列展示每个消费者的生成情况：
| 列 | 说明 |
| 消费者 | 消费者名称 / ID。 |
| 状态 | 生成中 / 成功 / 失败。 |
| 密钥名称/ID | 生成的密钥名称与 ID。 |
| 凭证内容 | 默认脱敏展示（如 sk-****7c3），单击显示可查看完整凭证。 |
| 原因 | 生成失败时展示失败原因。 |
七、密钥绑定消费者
消费者与密钥为一对多关系，一个消费者可以绑定多个密钥，一个密钥只可以绑定一个消费者。你可以为密钥绑定一个消费者。
1. 在消费者密钥列表页，单击目标密钥的“ID/名称”，进入详情页。
2. 单击添加资源，在新增资源弹窗中，左侧请选择消费者区域会列出所有可选的消费者，你可以通过搜索框快速查找。
3. 在左侧列表中，勾选一个需要绑定到该密钥的消费者，被选中的消费者会出现在右侧已选择列表中。
4. 如需移除消费者，可在右侧已选择列表中，单击某个消费者条目右侧的 × 图标，可将其从本组关联关系中移除，或直接选中新的消费者。
5. 调整完毕后，单击确定保存关联关系。
八、新建消费者时自动生成并关联密钥
在新建消费者时，可通过“关联密钥”字段选择自动生成并关联密钥，在创建消费者的同时由系统自动生成一个 API Key 类型密钥并自动关联，无需再单独新建与绑定。
1. 在消费者管理页面，切换到消费者（组）页签。
2. 单击新建消费者，打开新建消费者弹窗。
3. 填写消费者名称，选择所属消费者组。
4. 在关联密钥字段中选择密钥关联方式为自动生成并关联密钥，填写以下参数：
·密钥名称：必填，2-60个字符，支持中英文大小写、数字及分隔符（"-"、"_"），不能以数字和分隔符开头，不能以分隔符结尾。
·密钥描述：选填，最长200个字符。
5. 填写消费者描述（选填，最长200个字符）。
6. 单击确定，完成消费者创建。系统自动生成一个 API Key 类型密钥，并自动与该消费者关联。
九、查看密钥详情
1. 在消费者密钥列表页，单击目标密钥的“ID/名称”。
2. 进入密钥详情页，你可以查看：
·基本信息：包括密钥 ID、名称、类型、状态、创建时间等。
·已绑定消费者：展示当前密钥已关联的消费者信息。
十、编辑密钥
1. 在消费者密钥列表页，找到目标密钥，单击其操作列下的编辑；或在密钥详情页右上角单击编辑。
2. 在编辑密钥窗口中，支持修改密钥名称和描述（备注）信息。
3. 单击确定保存修改。
注意：说明：
注意：API Key 凭证创建后不可修改，如需更换请删除后重新创建。
十一、启用/禁用密钥
消费者密钥只有在启用状态下才可以生效，这意味着当密钥处于关闭或未激活状态时，AI 网关将无法识别或使用该密钥进行任何操作，因此在使用前务必确认密钥是否已正确启用。
1. 在消费者密钥列表页，找到目标密钥，单击其操作列下的禁用按钮后，密钥处于“已禁用”状态， AI 网关将无法识别或使用该密钥进行任何操作。
2. 启用操作需要在目标密钥处于“已禁用”情况下：单击启用，密钥将处于“启用”状态。
十二、删除密钥
1. 在消费者密钥列表页，找到目标密钥，单击其操作列下的禁用按钮后，才可以进行删除操作，等待密钥禁用后，单击删除即可。
2. 系统将进行删除前的依赖关系校验：
·若密钥已解除所有关联（消费者密钥需解除所有消费者关联），则弹窗直接显示密钥信息，单击确定即可删除。
·若密钥仍存在关联资源，弹窗会提示“存在未解除的依赖关系”并列出具体依赖项。你需要先解除所有依赖关系后，单击重新检查，校验通过后方可删除。
注意：事项：
十三、后续操作
创建消费者密钥后，需要在模型 API 或 MCP 服务上配置认证策略，声明该服务接受的认证方式及校验规则，详情请参见：
·配置模型 API 认证策略。
·配置 MCP 服务 访问控制。
十四、同步消费者密钥至多个实例
你可在全局视图消费者管理中，同步消费者密钥至多个实例。
1. 在左侧导航栏单击 消费者管理，按需切换 消费者组 / 消费者 / 消费者密钥 Tab。
2. 创建消费者组与消费者，填写名称、描述及凭证类型。
3. 在 消费者密钥 Tab，单击 新建，填写以下参数：
·凭证名称：填写凭证名称。
·所属消费者：选择关联的消费者。
·凭证类型：选择 API Key 或 JWT Secret。
4. 单击创建并同步到实例，进入同步弹窗，按需选择实例即可同步密钥至多个实例。
十七、Q1：如何选择合适的认证方式?
根据你的实际场景选择：
·API Key：简单场景，适用于内部服务或可信客户端，配置简单，性能最优。
·JWT：需要传递用户身份信息，支持自定义 Claims，适用于微服务间调用。
·OAuth 2.0：需要接入第三方 OAuth 服务，支持标准 OAuth 流程。
·OIDC：需要用户身份认证，支持 SSO（单点登录）。
十八、Q2：单个消费者可以配置多个凭证吗?
可以。单个消费者支持同时配置多种类型的凭证，例如：
·凭证1：API Key 类型。
·凭证2：JWT 类型。
·凭证3：OAuth 2.0类型。
客户端可以根据实际情况选择使用哪种凭证访问 API。
十九、Q3：JWT 的签名算法如何选择?
·HS256（对称加密）：使用密钥（Secret）进行签名和验证，配置简单，性能最优，适用于内部服务。
·RS256/ES256（非对称加密）：使用私钥签名、公钥验证，更安全，适用于需要分发公钥的场景。
如 JWT 由第三方服务颁发，需根据第三方服务使用的签名算法进行配置。
21、Q1：单个消费者最多可以配置多少个密钥凭证?
单个消费者最多可以配置20个凭证，支持多种类型混合配置。
22、Q2：OAuth 2.0支持哪些授权模式?
当前支持以下授权模式：
·Client Credentials（客户端凭证模式）：适用于机器对机器（M2M）场景。
·Password（密码模式）：适用于可信客户端场景。
暂不支持 Implicit（隐式模式）、Authorization Code（授权码模式）和 Refresh Token 流程。
24、Q1：生产环境如何管理认证凭证?
建议的管理实践：
1. 凭证轮换：定期更换凭证（如每季度更换一次），降低凭证泄露风险。
2. 有效期设置：为凭证设置合理的有效期（如1年），避免永久有效凭证泄露后持续被滥用。
3. 权限分离：为不同的业务系统创建不同的消费者，避免共用凭证。
4. 监控告警：监控认证失败率，异常流量及时告警。
5. 凭证存储：凭证信息存储在配置中心或密钥管理服务中，不要硬编码在代码中。
6. 泄露应急：如凭证泄露，立即禁用或删除该凭证，并创建新凭证。