---
title: "Provider connections"
description: "Connect one explicit upstream capability to a Workspace and understand how its immutable UUID selects requests."
---

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

# Provider connections

## Outcome

你可以解释一条 ProviderConnection 保存什么、如何被显式选择，以及为什么 Connection ID、模型名和 Provider Secret 具有不同职责。

## One connection, one explicit upstream capability

ProviderConnection 属于一个 Workspace，并包含：

| Field or fact     | Contract                                                               |
| ----------------- | ---------------------------------------------------------------------- |
| `id`              | Nexus 服务生成、创建后不可修改的 UUID。                                |
| `baseUrl`         | 管理端保存的上游 Origin 与基础路径；请求不能覆盖它。                   |
| `protocolProfile` | Transport 与 Usage 兼容性配置。                                        |
| Provider Secret   | 创建或轮换时写入，随后只保存加密值并返回脱敏 Preview。                 |
| `status`          | `ACTIVE`、`SUSPENDED` 或 `ARCHIVED`；Gateway 只解析可用连接。          |
| `gatewayBaseUrl`  | Nexus 根据部署 Gateway Origin 和 Connection UUID 计算的只读 Base URL。 |

## How the Gateway resolves a connection

```text
Inference Key
→ ApiKeyBinding → WorkspaceAccess → Workspace

Gateway Base URL
→ /providers/{providerConnectionId}

(workspaceId, providerConnectionId)
→ one ACTIVE ProviderConnection
```

Connection ID 必须属于认证 Key 所解析的 Workspace。相同 UUID 不能跨 Workspace 命中，客户端也不能在 URL、Header 或 Body 中提供另一个上游 Host。

## Path and payload behavior

```text
Nexus Base URL
https://gateway.nexus.microvoid.io/providers/533c4e1e-2823-4349-86b9-d6f1a869a2ca

SDK path
/chat/completions

ProviderConnection baseUrl
https://openrouter.ai/api/v1

Upstream target
https://openrouter.ai/api/v1/chat/completions
```

Gateway 保留剩余 Path、Query、Method 和 Body。`model` 是 Provider 定义的 Payload 字段，Nexus 不解析或重命名。

## Multiple connections stay explicit

一个 Workspace 可以保存多条 ACTIVE ProviderConnection。同一 WorkspaceAccess 默认可使用该 Workspace 的全部 ACTIVE Connection，并共享同一 Access Quota；每次请求仍由 Base URL 中的 UUID 明确选择一条连接。

切换 Connection 时，客户端必须使用目标 Provider 接受的原始模型名。Nexus 不保证两个 Provider 使用同一模型标识。

## Transport is not metering

安全的路径透传不等于该 Endpoint 已具备 Quota 计量。需要 Token Quota 的 Endpoint 还必须有匹配的 Usage Inspector；不支持的路径默认返回稳定的 `metering_unsupported` 类错误，而不是在无法结算时放行。

## Lifecycle and secret safety

- **Verify** 检查连接可用性，并记录 `lastVerifiedAt`；它不会把 Secret 返回给客户端。
- **Rotate secret** 更新加密 Provider Secret，不改变 Connection UUID、用户 Access 或 Inference Key。
- **Suspend or archive** 阻止新请求选择该连接；历史 Invocation、Usage 和 Audit 保留。

## Next steps

- [Credential model](/docs/give-users-access/credential-model)
- [Use my Nexus access](/docs/quickstarts/use-my-nexus-access)

Source: https://nexus.microvoid.io/docs/connect-model-capacity/provider-connections/index.mdx