Rotate a provider secret

Replace an upstream provider credential without changing user keys or the Gateway Base URL.

Goal

为一条 ProviderConnection 更换上游 Provider Secret，而不触碰最终用户凭证。

Outcome

ProviderConnection 的服务生成 UUID、Gateway Base URL、WorkspaceAccess 和 Inference Key 保持不变；响应只显示 secretPreview，不返回 Secret 明文。

Prerequisites

ProviderConnection ID、Management Key 和新的上游 Provider Key。
已确认新 Key 可以访问该连接需要的模型。

Lifecycle note

这是 ProviderConnection 凭证版本变化，不是新建连接。不要通过创建新 UUID 来完成常规 Secret 轮换，否则所有客户端 Base URL 都要迁移。

1. Rotate from a backend process

rotate-provider-secret.mjsjs

const adminBaseUrl = required('NEXUS_ADMIN_BASE_URL').replace(/\/$/, '');
const managementKey = required('NEXUS_MANAGEMENT_KEY');
const providerConnectionId = required('NEXUS_PROVIDER_CONNECTION_ID');
const providerApiKey = required('NEXUS_PROVIDER_API_KEY');

const response = await fetch(`${adminBaseUrl}/admin/v1/provider-connections/${providerConnectionId}/rotate-secret`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${managementKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ apiKey: providerApiKey }),
});
if (!response.ok) throw new Error(`rotation failed: ${response.status} ${await response.text()}`);
const connection = await response.json();
console.log(
  JSON.stringify({
    id: connection.id,
    gatewayBaseUrl: connection.gatewayBaseUrl,
    status: connection.status,
    secretPreview: connection.secretPreview,
  }),
);

function required(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(`${name} is required`);
  return value;
}

Terminalsh

export NEXUS_ADMIN_BASE_URL="https://nexus.microvoid.io"
export NEXUS_MANAGEMENT_KEY="<NEXUS_MANAGEMENT_KEY>"
export NEXUS_PROVIDER_CONNECTION_ID="<PROVIDER_CONNECTION_UUID>"
export NEXUS_PROVIDER_API_KEY="<NEW_PROVIDER_SECRET>"
node rotate-provider-secret.mjs

Check your work

运行 Verify provider connection，再用既有用户 Base URL 和 Inference Key 发起测试请求。返回的 id 和 gatewayBaseUrl 应与轮换前一致。

Failure modes

Provider 验证返回认证失败：保持旧凭证的上游撤销窗口，修复新 Key 权限后再切换。
provider_configuration_error：检查保存的 Base URL/加密配置；不要把任意 Host 传给客户端。
provider_unavailable：用同一 x-nexus-request-id 查看 Provider Attempt，再决定是否重试。

Security notes

不要把 NEXUS_PROVIDER_API_KEY 放在命令历史、CI 输出或 VITE_* 变量。Provider Secret 必须加密保存、短时解密且不进入日志。

Next steps

轮换完成并验证后，按 Provider 自己的流程撤销旧 Key。用户无需更换 Inference Key。