---
title: "Rotate a provider secret"
description: "Replace an upstream provider credential without changing user keys or the Gateway Base URL."
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate a provider secret

## 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

```js title="rotate-provider-secret.mjs"
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;
}
```

```sh title="Terminal"
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](/api-reference/admin/provider-connections/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。

Source: https://nexus.microvoid.io/cookbook/rotate-provider-secret/index.mdx