客户范围的 AI API 密钥：隔离租户、预算和滥用，而不会导致提供商密钥蔓延
SaaS 产品、代理机构和经销商平台需要客户级 AI 访问权限，而无需暴露上游提供商凭据。使用网关颁发的虚拟密钥作为租户属性、模型访问、预算、速率限制、撤销、轮换和使用分类账的策略句柄。
当产品允许许多客户调用人工智能模型时，错误的原语通常是上游提供商密钥。提供程序密钥通常代表帐户、项目、工作区或服务帐户。您的产品需要更窄的东西：一个面向客户的密钥，用于标识一个租户、客户、应用程序、环境、模型策略、预算和审核规则。
这就是客户范围内的 AI API 密钥的目的。网关发出密钥、验证请求、应用策略、计量使用情况，然后使用隐藏凭据调用上游提供商。下游客户永远不会收到提供商密钥。他们与您的平台签订了稳定的合同。
读者问题：每个客户没有一个提供商项目的客户隔离
SaaS 构建者、代理机构和经销商平台通常需要回答实际问题，然后才能向下游公开 AI 访问权限：
- 哪个客户产生了此使用情况？
- 哪个应用程序、环境或集成发出了调用？
- 允许哪些模型和方式？
- 该客户本月可以花多少钱？
- 如果密钥泄漏会发生什么？
- 能否在不影响其他人的情况下暂停该客户？
- 稍后可以根据提供商报告对使用情况进行核对吗？
提供商方项目和工作区可以提供帮助，但它们并不总是适合每个下游客户。为每个客户创建一个上游边界可以改善硬隔离和报告，但也会产生配置开销、配额碎片、凭证蔓延和更多协调工作。
即使上游凭据被池化，网关颁发的密钥也可以为产品提供客户级控制点。当客户需要合同分离、居住边界或直接提供商帐户所有权时，它还支持更强大的模式，例如租户绑定的提供商凭据或自带密钥。
事实、建议和预测
事实
- OpenAI 项目支持成员、服务帐户、API 密钥、使用限制、预算和范围内的项目资源。这使得项目可以作为上游边界，但不会自动成为每个最终客户的正确基元。
- OpenAI 使用情况报告可以按项目、用户、API 密钥、模型、批次和服务层等维度对使用情况进行分组。 SaaS 退款仍然需要将这些提供商记录与产品拥有的客户标识符相结合。
- 人性化工作区按用例、团队、部门、项目或产品分隔 API 资源。 API 密钥与创建它们的工作区相关联，并且无法在工作区之间移动。
- 人性化使用情况和成本报告支持按 API 密钥、工作区、模型、服务层、上下文窗口、数据驻留和速度相关选项进行分组，并以每日美元金额形式返回成本。
- Google Gemini API 密钥指南建议限制密钥，并且默认情况下，Gemini API 密钥仅限于生成语言 API。根据部署形状，可能会出现 IP 地址等应用程序限制。
- OWASP 指南将 API 密钥视为受保护端点的必需控制，并表示当客户端违反使用协议时应撤销密钥。
- OWASP 机密指南强调最低权限、不再需要机密或机密被泄露时的撤销以及自动轮换以减少实施错误。
建议
- 使用网关颁发的客户密钥作为策略句柄，而不仅仅是身份验证令牌。
- 对下游客户隐藏上游提供商凭据。
- 在依赖提供商仪表板之前，在请求时编写网关使用分类帐。
- 有选择地为高风险、大批量、受监管、对居住地敏感或合同独立的客户使用提供商项目或工作区。
- 将密钥轮换构建为重叠工作流程，而不是立即破坏事件。
预测
- 更多提供商将提供更丰富的使用分组和预算控制，但 SaaS 计费和经销商报告仍然需要产品拥有的客户归因。
- 经销商和代理平台将越来越多地将网关密钥视为商业对象：与计划、信用余额、范围和支持工作流程相关联。
- 具有严格合规性或采购需求的客户会要求 BYOK 或提供商帐户所有权，而大多数普通客户更喜欢托管网关合同。
网关密钥对象
客户范围的密钥应解析为结构化策略对象。至少，将密钥建模为不仅仅是哈希值和名称。
<前><代码>{ "key_id": "key_01J9...", “tenant_id”：“tenant_acme”， “customer_id”：“cust_4812”，“application_id”：“app_support_bot”， “环境”：“生产”， “所有者”：{ “类型”：“服务帐户”， “id”：“svc_support_ai” }, "model_profile_id": "profile_support_standard", “allowed_modalities”：[“文本”，“图像输入”]， "tool_policy_id": "tools_readonly_kb", “每月预算”：{ “货币”：“美元”， “金额”：“500.00” }, “速率限制”：{ “每分钟请求数”：120， “每分钟输入令牌”：250000， “每分钟输出令牌”：80000 }, "retention_policy": "metadata_only", “状态”：“活跃”， “创建时间”：“2026-09-05T10:00:00Z”， “last_used_at”：空 }确切的字段会有所不同，但原则应该不变：每个传入请求在分派之前都会将密钥解析到租户策略中。身份验证回答“谁在打电话？”策略解析回答“这个调用者可以做什么，他们可以花多少钱，请求路由在哪里，以及必须记录什么？”
这也是语义产品策略的重要性所在。销售面向代理机构的 AI API 的平台可能需要客户和营销活动维度。开发人员工具可能需要工作空间和存储库维度。经销商可能需要与其计费系统相匹配的外部客户 ID。
密钥创建工作流程
密钥创建应该具有足够的确定性以实现自动化，并且足够严格以进行安全审查。
1。首先创建客户记录
不要创建孤立键。密钥在存在之前应属于租户和客户记录。对于经销商平台，客户记录应包括来自经销商 CRM 或计费系统的外部 ID、计划元数据、税收或发票分组（如果需要）以及可以暂停所有子密钥的状态字段。
2。附加模型配置文件
模型配置文件将面向客户的模型名称映射到提供商模型和功能。例如，support-standard 可能允许平衡文本模型、图像输入，但不执行任何代码。 research-premium 可能允许长上下文模型、网络搜索和更高的每个请求上限。
不要强制下游应用程序对提供程序模型 ID 进行硬编码。使用网关配置文件来管理可用性、后备、定价和弃用。
3。设置支出和速率限制
同时使用预算和费率限制。每月预算可以防止发票随着时间的推移而损坏。速率限制可防止突然滥用、重试风暴或意外循环在几分钟内耗尽整个预算。
有用的控件包括：
- 每月客户预算。
- 用于异常检测的每日软上限。
- 每键请求率。
- 输入和输出令牌率。
- 每个请求的最高预计费用。
- 针对托管搜索、文件处理或代码执行的工具特定限制。
预算执行应当在发送前预留预计成本，完成后结算实际成本，未使用的储备金予以释放。这会将关键策略连接到AI API 计费，而不是将计费视为延迟报告任务。
4。正确生成并存储秘密
显示一次明文秘密。仅存储强哈希值，以及用于支持查找的短前缀或指纹。该前缀可帮助支持团队识别“以 8F2A 结尾的密钥”，而无需查看秘密。
典型的存储模式是：
key_id：稳定的数据库标识符。secret_hash：使用适当的密码或令牌哈希策略对完整密钥进行哈希处理。secret_prefix：短的非敏感显示前缀。指纹：审核查找的确定性标识符。created_by：创建密钥的用户或合作伙伴 API 客户端。状态：有效、正在耗尽、已撤销、已隔离、已过期。
切勿将上游提供商密钥存储在客户密钥对象上。提供商凭据属于单独的凭据保管库，具有自己的访问规则。
请求时执行
网关应将每个模型调用视为一个策略决策，然后进行提供程序调度。实际的请求路径如下所示：
- 解析提供的网关密钥。
- 查找密钥哈希值和状态。
- 解析租户、客户、应用、环境、所有者和模型配置文件。
- 检查租户和客户是否活跃。
- 验证请求的模型别名、模式、工具、保留模式、区域和服务层级。
- 估算请求成本和预留预算。
- 检查速率限制和滥用阈值。
- 选择上游凭据模式：池化、租户绑定或 BYOK。
- 发送给提供商。
- 捕获使用情况、成本、提供商参考、错误和安全信号。
- 结算预算预留并编写最终账本事件。
此序列使网关对客户合同负责。提供商仪表板成为协调输入，而不是唯一的事实来源。
以后实际有帮助的使用分类帐字段
网关分类账应该保留足够的详细信息来回答支持、计费、滥用和路由问题，默认情况下不需要原始提示存储。
有用的字段包括：
request_id和trace_id。tenant_id、customer_id、application_id和key_id。- 最终用户标识符，在适当的情况下最好使用假名。
- 客户请求的模型别名。
- 解决了上游提供商和模型的问题。
- 输入、输出、推理、缓存、音频、图像、视频和工具使用（如果适用）。
- 报价成本、预留金额、结算成本、货币和定价目录版本。
- 提供商请求 ID、使用情况报告参考、项目、工作区或 API 密钥分组维度（如果有）。
- 已应用保留政策。
- 安全、滥用或政策决策代码。
- 错误类别和重试元数据。
此结构支持退款、客户支持、事件响应和 API 密钥管理工作流程，该工作流程可以回答“这个密钥做了什么？”不暴露不相关的租户。
凭据模式：池化、租户绑定和 BYOK
汇集的提供商凭证
在默认模式下，许多客户密钥通过较小的一组提供商凭据进行路由。这操作起来很简单，并且减少了提供商方面的蔓延。当网关具有强大的租户属性、预算执行、速率限制、滥用隔离和缓存边界控制时，它就可以发挥作用。
权衡是提供商方报告可能仅显示网关凭证或提供商项目。您必须将提供商记录连接回网关分类帐记录，以生成客户级别的计费和分析。
租户绑定的提供商凭据
对于规模较大或风险较高的租户，请将租户绑定到专用提供商项目、工作区、服务帐户或密钥。这提供了更强的上游分离，并可以简化提供商方报告。如果提供商支持该边界的限制，它还可以提供硬配额支持。
成本是操作复杂性。供应、轮换、提供商限制、事件响应和协调现在发生在更多上游对象上。
带上你自己的钥匙
当客户必须拥有提供商帐户、协商自己的提供商合同或将提供商账单分开时，BYOK 会很有用。网关仍然尽可能应用模型配置文件、路由策略、分析和应用程序级控制。
权衡是支持复杂性。每个客户的提供商帐户可能具有不同的模型访问权限、配额、定价、保留设置和事件状态。网关必须清楚地检测并解释这些差异。
撤销和隔离
撤销应立即阻止对客户密钥的新请求，而无需轮换不相关的上游提供商凭据。这是虚拟按键的主要优点之一。
对不同的操作操作使用不同的状态：
活动：允许请求。耗尽：在轮换窗口期间接受旧密钥，但会发出警告和审核事件。已撤销：新请求将被永久拒绝。已隔离：新请求因滥用、付款、政策或事件响应而被阻止。已过期：密钥已超过其生命周期，必须更换。
事件解决后，隔离应该可以撤销。撤销通常不应是可逆的，因为恢复旧秘密会增加混乱和风险。
当密钥违反使用政策时，记录原因、参与者、时间和执行范围。如果决策是自动进行的，请保留触发该决策的规则版本和信号。这使客户对话保持真实。
轮换而不中断生产
密钥轮换应使用两密钥重叠工作流程：
- 使用相同的客户、应用程序、型号配置文件和限制创建替换密钥，除非操作员故意更改。
- 显示新密码一次。
- 将旧密钥标记为
正在耗尽。 - 在一定期限内接受这两个密钥，例如 7、14 或 30 天，具体取决于客户计划和风险。
- 在排水键上发出使用警告。
- 如果临近截止日期仍使用旧密钥，请通知所有者或合作伙伴 API 客户端。
- 在窗口末尾撤销旧密钥。
- 在同一客户和应用下保留两个关键 ID 的归因。
这避免了安全改进导致生产中断的常见故障模式。轮换仍然是一种控制，但它成为一个有证据和截止日期的操作工作流程。
合作伙伴 API 界面
如果下游平台以编程方式管理客户，请通过合作伙伴 API 公开关键操作。 API 应支持幂等性密钥和审核事件，因为配置通常发生在计费、入职或 CRM 工作流程内。
最小端点：
POST /customers：创建或更新插入客户。POST /customers/{customer_id}/keys：创建密钥。GET /customers/{customer_id}/keys：列出密钥和状态。PATCH /keys/{key_id}：更新范围、所有者、限制、模型配置文件或状态。POST /keys/{key_id}/rotate：创建替换并将旧密钥标记为正在耗尽。POST /keys/{key_id}/revoke：立即撤销。GET /customers/{customer_id}/usage：按时间范围、键、应用、模型或最终用户维度返回使用情况和费用。
每个变异请求都应该接受幂等密钥。每个更改都应编写一个审核事件，其中包含参与者、目标、前后字段、源 IP 或客户端身份以及可用的原因。
何时使用提供程序项目或工作区
不要将网关密钥和提供商边界视为互斥的。他们解决不同的问题。
使用网关密钥进行正常的客户级别控制：
- 每个客户的归因。
- 每个应用程序密钥。
- 预算和费率限制。
- 快速暂停。
- 轮换工作流程。
- 使用情况分析和经销商报告。
当客户需要更强的分离时，添加提供商项目、工作区或专用提供商凭证：
- 每月的交易量很高，值得专门的配额。
- 具有明确驻留或保留要求的受监管工作负载。
- 合同发票分离。
- 提供商方的严格预算或配额保障。
- 专门的滥用监控或安全审查边界。
- 客户通过 BYOK 拥有的提供商帐户。
实际的默认设置是网关强制隔离，具有选择性上游硬边界。这样可以保持通用路径简单，同时为需要更多隔离的客户保留升级路径。
实施清单
- 定义包含租户、客户、应用、环境、所有者、模型配置文件、限制、保留政策和状态的客户密钥架构。
- 对静态密钥进行哈希处理并仅显示明文一次。
- 将网关密钥与上游提供商凭据存储分开。
- 在发送之前将每个请求解决为政策。
- 在致电提供商之前预留预算，并在了解最终使用情况后进行结算。
- 记录使用情况，包括客户、密钥、模型别名、上游模型、代币类别、工具使用情况、报价成本、结算成本和提供商参考信息。
- 实施有效、耗尽、撤销、隔离和过期状态。
- 支持两键旋转重叠。
- 使用幂等密钥公开合作伙伴 API 操作。
- 仅在运营成本合理的情况下使用提供商项目或工作区。
可行的结论
AI 访问的客户隔离通常应从网关密钥开始，而不是从提供商密钥开始。网关密钥是面向客户的合同：它命名租户、客户、应用程序、模型配置文件、预算、速率限制、保留规则和审核策略。提供者密钥是该合约背后的实现细节。
该架构为 SaaS 构建者和经销商平台提供快速撤销、准确归因、每个客户预算、受控轮换和有用的使用分析，而无需默认为每个客户创建一个上游提供商项目。当风险、数量、驻地或合同需要时，使用上游项目、工作区、租户绑定凭据或 BYOK。对于普通路径，在网关账本和策略引擎中强制实施客户隔离，然后协调提供商记录。