灵渠 LingQu
治理与配额

密钥治理

API 密钥子账户的发放维度与归属、必需请求头校验、访问范围与按密钥路由约束、有效期与轮换。讲清每一把密钥如何成为可追溯、可约束、可回收的请求凭据

API 密钥是灵渠平台治理体系中的核心凭据。客户应用调用数据平面 /v1/* 时，以密钥发起鉴权；平台据此判定请求由谁发出、归属到哪个子账户分账，并把挂在该密钥上的访问范围、路由约束、预算与限速一并施加。一把密钥既是请求的入场券，也是治理的最小作用单元。

本页讲清密钥的完整生命周期：按什么维度发放与归属、如何用必需请求头补强归属、如何约束密钥的访问范围与路由目标、如何设定有效期并安全地轮换。密钥的管理接口集中在控制平面 /api/v1/keys，仅控制台可见，具体端点契约见 API 参考 · 控制平面。

1. 发放与归属维度

密钥以子账户形态发放——每一把密钥对应一个分账归属，用量逐请求归到对应子账户。发放时声明归属维度，让密钥从一开始就携带清晰的组织语义。

维度含义典型用法
department部门按组织部门分账，统计各部门的查询用量与费用
business-line业务线按业务线分账，核算单条业务的模型调用成本
cost-center成本中心按成本中心分账，对接内部财务核算口径

创建一把密钥，声明名称、归属维度、访问范围与有效期：

curl https://<平台入口地址>/api/v1/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "营销业务线-生产",
    "dimension": "business-line",
    "model_scope": ["<模型中性名>"],
    "expires_at": null
  }'
字段含义
name密钥可读名称，用于在列表与分账中识别
dimension归属维度（department / business-line / cost-center）
model_scope允许调用的模型范围（留空即全部，见 §3）
expires_at过期日期（留空即永不过期，见 §5）

新建密钥的摘要中包含密钥本体，仅在创建时返回一次，请妥善保存：

{
  "api_key_id": "<子账户标识>",
  "key": "tsxt-************************",
  "dimension": "business-line",
  "status": "active"
}

归属与汇总。 密钥统一以 tsxt- 前缀签发。全部子账户密钥共用账户层的一层汇总信用额度——平台不设逐密钥子额度。当汇总额度达上限时，全部密钥一并暂停（详见 预算与限速 与 信用额度接口）。

2. 必需请求头

除密钥本身外，平台可要求每一次数据平面请求携带若干必需请求头，用于补强归属与可追溯性。请求若缺少任一必需头，会在治理前置环节被直接拒绝（400），不进入后续路由。

典型必需头用途
X-Tenant-Id标识调用方租户归属，强化多租户隔离
X-Correlation-Id跨服务的请求追踪标识，便于端到端关联
自定义业务头承载客户基础设施依赖的元数据

请求头匹配大小写不敏感——配置 X-Tenant-Id 同样匹配 x-tenant-id。一次携带必需头与密钥的合规请求：

curl https://<平台入口地址>/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "X-Tenant-Id: <租户标识>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型中性名>",
    "messages": [ { "role": "user", "content": "你好" } ]
  }'

缺失必需头时，平台在转发上游前返回结构化错误：

{
  "error": {
    "code": "missing_required_headers",
    "message": "缺少必需请求头：x-tenant-id",
    "request_id": "<请求追踪标识>"
  }
}

必需头校验与密钥校验是两道独立的闸门，按"先必需头、后密钥"的次序执行。两者均配置时，请求须同时满足才能放行。必需头清单在控制台「平台设置 · 接入参数」配置，改动即时生效。

3. 访问范围约束

每一把密钥可限定其能调用的模型范围。访问范围在路由之前求值——越权模型在请求触达上游前即被拒绝，既守住权限边界，也避免无谓的上游探测。

model_scope 取值语义
留空（[]）不限制，允许调用平台对外提供的全部模型
显式模型列表仅允许列表内的模型；其余模型一律拒绝

变更某把密钥的访问范围，提交新的模型列表：

curl https://<平台入口地址>/api/v1/keys/<子账户标识> \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "model_scope": ["<轻量模型中性名>", "<旗舰模型中性名>"]
  }'

请求的模型不在范围内时，平台返回：

{
  "error": {
    "code": "model_blocked",
    "message": "模型 <模型中性名> 不在该密钥的允许范围内",
    "request_id": "<请求追踪标识>"
  }
}

访问范围约束的是"客户侧可声明哪些模型"，与路由中间件"实际择优选定哪个上游模型"是两件事——前者是权限边界，后者是管道内的智能调度（见 中间件管道 §2.3）。

4. 按密钥路由约束

除模型范围外，密钥还可携带路由约束，把该密钥的流量绑定到指定的上游分组或上游标识。这让不同密钥在同一平台上走不同的上游目标，常用于环境隔离与成本归集。

约束维度说明
上游分组限定密钥只命中某个路由分组内的上游（如「生产组」「测试组」）
上游标识进一步限定到分组内的特定上游接入
curl https://<平台入口地址>/api/v1/keys/<子账户标识> \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "routing_scope": {
      "provider_group": "production",
      "provider_ids": ["<上游标识>"]
    }
  }'

典型用法：

场景配置
环境隔离生产密钥绑「生产组」、测试密钥绑「测试组」，互不串流
成本归集不同业务线密钥绑各自的上游接入，按上游账单归口核算
权限收敛敏感工作负载限定到经过合规接入的上游，不落到通用池

按密钥路由约束与密钥的模型访问范围叠加生效：请求须同时满足"模型在允许范围内"且"目标上游在路由约束内"才被放行。路由约束在路由中间件择优前作为候选集过滤——被约束排除的上游不参与本次加权择优。上游分组与优先级 / 权重的配置详见 多上游模型接入。

5. 有效期、启停与轮换

密钥的生命周期支持有效期控制、即时启停与安全轮换，覆盖从发放到回收的全过程。

5.1 有效期

发放时以 expires_at 设过期日期，留空即永不过期。到期后密钥自动失效，数据平面以该密钥发起的请求被拒。

5.2 即时启停

无需删除密钥即可临时收回其访问能力——暂停后该密钥的请求立即被拒，恢复后即时复用，便于灰度与应急止血：

# 暂停
curl https://<平台入口地址>/api/v1/keys/<子账户标识>/suspend \
  -X POST -H "Cookie: <控制台会话凭证>"

# 恢复
curl https://<平台入口地址>/api/v1/keys/<子账户标识>/resume \
  -X POST -H "Cookie: <控制台会话凭证>"

5.3 轮换

密钥轮换遵循"先发新、后停旧"的双活窗口，避免业务中断。轮换流程如下：

发放新密钥 应用切到新密钥 旧密钥暂停 旧密钥注销 回退到旧密钥 在用 双活 切换中 仅新密钥
步骤动作说明
1发放新密钥同维度、同访问范围创建一把新密钥，进入双活窗口
2应用切换客户应用将鉴权头切到新密钥，新旧并行验证
3暂停旧密钥确认新密钥稳态后暂停旧密钥（可即时恢复以便回退）
4注销旧密钥观察期无异常后注销旧密钥（软注销，密钥本体不可复用）

注销为软注销——历史用量与分账记录保留可查，但密钥本体不可再用于鉴权，也不可复用同一密钥串。注销不影响已落账的历史用量。轮换全程不触及账户层的汇总信用额度，额度按账户口径连续计量。

相关链接

治理与配额

灵渠平台的三层治理模型——账户归属、密钥发放、预算与限速。一页讲清密钥/预算/限速如何协同约束每一次查询请求，再分页指引到密钥治理与预算限速两节

预算与限速

周期预算、模型级限额与速率限制三类配额约束的配置形态、重置周期与触发行为。讲清每一项约束如何独立校验、逐请求扣减，以及达额与超速时的拦截语义

On this page

1. 发放与归属维度2. 必需请求头3. 访问范围约束4. 按密钥路由约束5. 有效期、启停与轮换5.1 有效期5.2 即时启停5.3 轮换相关链接