LLM API Virtual Keys
Expose Policy, Protect Provider SecretsLLM API 虚拟密钥：向应用暴露策略，保护上游密钥

TL;DR

Virtual key versus provider key虚拟密钥与供应商密钥

Applications present a virtual key to the gateway. The gateway authenticates it, resolves identity and policy, then selects an approved upstream route using a provider credential that never leaves the trusted boundary.

应用向网关提交虚拟密钥。网关完成认证后解析身份与策略，再使用始终留在可信边界内的供应商凭证选择获批上游路由。

A provider key usually grants access according to the provider account or project that issued it. A virtual key is an internal authorization object: it can represent one service, tenant, environment, team or temporary workload, even when several virtual keys ultimately use the same upstream account. That additional identity layer is what makes per-application budgets, model allowlists and audit ownership possible.

供应商密钥通常按照签发它的供应商账户或项目授予权限；虚拟密钥则是内部授权对象，可以代表某项服务、租户、环境、团队或临时工作负载，即使多个虚拟密钥最终共用同一个上游账户也不例外。正是这层额外身份，才让应用级预算、模型白名单与审计归属成为可能。

Do not encode sensitive policy in the key itself. Store a one-way identifier and versioned server-side policy so permissions can change and keys can be revoked without disclosure. The visible token should carry enough entropy to resist guessing, while ownership, scope, expiry and budget remain server-side records.

不要把敏感策略直接编码进密钥。应保存单向标识和版本化服务端策略，使权限能够调整、密钥能够吊销且无需披露内部规则。外部 Token 需要具备足够熵值以抵抗猜测，而所有者、权限范围、到期时间和预算应保存在服务端。

Virtual keys are most valuable when their lifecycle is shorter and more specific than the upstream credential. Issue separate keys for production, staging, CI jobs and local development; name an accountable owner; set an expiry where practical; and avoid copying a human user's key into a long-running service. If two workloads need different data regions or model families, they should not share one virtual key merely for convenience.

当虚拟密钥的生命周期比上游凭证更短、用途更明确时，它的价值最大。生产、预发布、CI 任务和本地开发应分别签发密钥，指定可追责的所有者，并在可行时设置到期时间；不要把个人用户密钥复制到长期运行的服务中。如果两项工作负载需要不同的数据区域或模型族，也不应为了方便而共用同一个虚拟密钥。

Credential design choices凭证设计选择

Virtual key policy controls虚拟密钥策略控制

Validate the control plane验证控制平面

Control-plane testing must cover both authorization correctness and operational propagation. Creating a key in one region, changing its policy in another and revoking it during active traffic should produce deterministic results within documented time bounds. Test against multiple replicas so a stale cache cannot continue accepting a key that another replica has already revoked.

控制面测试既要覆盖授权正确性，也要覆盖策略传播。在一个区域创建密钥、在另一区域修改策略，并在活跃流量中吊销密钥时，系统都应在承诺的时间范围内产生确定结果。测试需要跨多个副本执行，避免某个陈旧缓存继续接受已被其他副本吊销的密钥。

• Attempt cross-tenant, wrong-model, expired and revoked-key requests.
• Verify limits under bursts and ensure decisions are atomic across replicas.
• Rotate upstream credentials without changing application virtual keys.
• Trace every accepted and denied request to identity, policy version and route.

• 尝试跨租户、未授权模型、过期密钥与已吊销密钥请求。
• 在突发流量下验证额度，并确保多副本之间的决策具备原子性。
• 在不更改应用虚拟密钥的情况下轮换上游凭证。
• 把每个接受或拒绝的请求关联到身份、策略版本和路由。

Budget tests need concurrency, not just sequential calls. Reserve spend before dispatch when several requests can race against the same limit, reconcile the reservation with actual token usage afterward, and define whether a request is rejected, queued or routed to a cheaper model when the budget is exhausted. Verify that retries do not charge the virtual-key budget twice for one logical attempt.

预算测试不能只做顺序调用，还必须覆盖并发场景。当多个请求可能同时竞争同一额度时，应在分发前预留预算，完成后再按实际 Token 用量结算；同时明确预算耗尽时请求是被拒绝、排队，还是路由到更便宜的模型。还要验证重试不会让同一次逻辑调用被重复扣减虚拟密钥预算。

Terminate virtual keys at the gateway在网关终止虚拟密钥

A user or service authenticates with a virtual key or identity token. The gateway resolves an internal principal, evaluates versioned policy and selects an allowed model route. Provider secrets are fetched from a protected vault and never returned to the application.

用户或服务使用虚拟密钥或身份 Token 完成认证。网关解析内部主体、评估版本化策略并选择允许的模型路由。供应商密钥从受保护的密钥库中获取，永不返回应用。

Store only a hash or keyed digest of the virtual key where possible, and show the plaintext value only at creation. Requests should be authenticated before large bodies are buffered or expensive work begins. After authentication, attach the resolved principal and policy version to the request context so every downstream routing, logging and billing decision uses the same identity.

在可行时只存储虚拟密钥的哈希或带密钥摘要，并仅在创建时展示一次明文。系统应在缓冲大体积请求或启动高成本工作前完成认证。认证后，把解析出的主体与策略版本附加到请求上下文中，使后续路由、日志和计费决策始终使用同一身份。

Design for partial control-plane failure. Runtime gateways can cache signed policy snapshots for a short, bounded interval, but revocation and high-risk policy changes need a fast invalidation channel. Define fail-open versus fail-closed behavior by workload: a low-risk internal summarizer may tolerate a brief cached policy, while regulated data access should normally stop when policy freshness cannot be established.

还要考虑控制面局部故障。运行时网关可以在短暂且有边界的时间内缓存已签名策略快照，但吊销操作和高风险策略变更需要快速失效通道。不同工作负载应分别定义故障时放行还是拒绝：低风险内部摘要任务可以短暂使用缓存策略，而受监管数据访问通常应在无法确认策略新鲜度时停止。

Use separate scopes for models and external capabilities为模型与外部能力使用独立权限范围

Model virtual keys govern inference access. QVeris governs external APIs, tools, services and live data through Discover → Inspect → Call. Bind both to the same identity where useful, but issue separate scopes, budgets and audit records.

模型虚拟密钥治理推理访问；QVeris 通过“发现 → 检查 → 调用”治理外部 API、工具、服务和实时数据。两者可以绑定同一身份，但应签发独立的权限范围、预算和审计记录。

A support assistant, for example, may be allowed to use several text models but only read ticket metadata and public documentation. A finance agent may use the same models yet require market data, filings and portfolio tools with different entitlements. Model access alone cannot express those distinctions, so external capability policy should name the allowed tools, permitted data classes, argument limits and any required human approval.

例如，客服助手可以使用多个文本模型，但只能读取工单元数据和公开文档；金融 Agent 即使使用相同模型，也可能需要带不同授权的市场数据、监管申报文件和投资组合工具。仅靠模型访问权限无法表达这些差异，因此外部能力策略应明确允许的工具、数据分类、参数限制和必要的人工审批。

Join the records at the workflow level rather than forcing them into one credential. A shared trace can show that a virtual key authorized model inference and that a separately scoped QVeris capability produced the live result. This gives operators one investigation path while preserving separate revocation, cost attribution and least-privilege controls.

应在工作流层关联记录，而不是把两类权限强行塞进同一个凭证。一条共享调用链可以同时说明：虚拟密钥授权了模型推理，另一个独立授权的 QVeris 能力生成了实时结果。这样运营人员仍有统一的调查路径，同时保留独立吊销、成本归属和最小权限控制。

FAQ

Official sources and further reading官方资料与延伸阅读