---
title: "Add Nexus to my product"
description: "Connect provider capacity and complete one quota-managed application-user request."
---

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

# Add Nexus to my product

## Goal

从一个空 Workspace 开始，让一名真实应用用户通过 Nexus Gateway 完成请求，并在 Console 中看到该用户、ProviderConnection、Quota 和 Usage 的归因。

## Outcome

完成后，你的应用后端保留 Nexus 管理权限；应用用户只收到一个带有不可变 `providerConnectionId` UUID 的 Gateway Base URL 和一次性展示的 Nexus Inference Key。

## Who this is for

负责接入 Nexus、管理 Provider 凭证并把 AI 能力分配给应用用户的平台开发者。

## Prerequisites

- 一个可登录的 Nexus Console 和可创建 Workspace 的 Organization。
- 目标 Provider 的上游 Base URL、Provider Key，以及该 Provider 接受的原始模型名。
- 应用中的稳定用户 ID 和邮箱。
- 本地 Node.js 22.12+；示例使用 E2E 锁定的 OpenAI JavaScript SDK。

> **Keep credentials in their plane**
>
> Provider Key 只输入 Console 的 Provider 连接表单；不要把它交给应用用户。Console 使用登录 Session
> 操作管理面，应用用户最终只得到 Inference Key。

## 1. Create a Workspace

在 Console 打开 **Workspaces**，填写名称和小写 kebab-case Slug，然后选择 **Create Workspace**。Workspace 是 ProviderConnection、Plan、Access、Quota 和 Usage 的隔离边界。

## 2. Connect your provider

进入 Workspace 的 **Providers** 页面，选择 **Connect provider**：

1. 选择与上游协议一致的 Adapter。
2. 确认连接名称和上游 Base URL。
3. 输入 Provider Key 并创建连接。
4. 选择 **Verify**，确认 Nexus 能用已加密保存的凭证访问上游。
5. 复制 Console 展示的 Gateway Base URL。URL 中的最后一个路径段是服务生成、不可变的 `providerConnectionId` UUID。

客户端不能提交上游 Host；Gateway 只按 `(workspaceId, providerConnectionId)` 查找已保存的连接。

## 3. Create a Plan

进入 **Plans** 并创建一个 Plan + QuotaStrategy。填写 Plan 名称、稳定 Key、重置周期、Quota Units、输入/输出倍率和最大输出 Token。Console 会按已接受的管理流程创建 Plan 与策略、发布策略、绑定策略并发布 Plan。

首次验证可以使用一组足够完成单次请求的本地测试值；Quota Unit 是 AI 使用权，不是货币余额。

## 4. Provision a user

进入 **Users**，选择 **Provision user**，填写应用的 `externalUserId`、邮箱、可选姓名并选择刚发布的 Plan。选择 **Provision User + Inference Key**。

立即安全保存一次性展示的 Inference Key。关闭对话框后不能再次读取明文；丢失时应签发新 Key，而不是查询旧值。

## 5. Call a model

安装与 E2E 相同的 SDK 版本：


```sh title="Terminal"
npm install openai@6.48.0
```


下面的环境值来自公开 Fake Provider 兼容性 Fixture。把 Base URL 替换为 Console 复制的值，把 Key 占位符替换为刚签发的 Inference Key，并使用所选 Provider 接受的原始模型名。


```sh title="Terminal"
export NEXUS_BASE_URL="https://gateway.nexus.microvoid.io/providers/00000000-0000-0000-0000-000000000141"
export NEXUS_API_KEY="<NEXUS_INFERENCE_KEY>"
export NEXUS_MODEL="provider/opaque-model-v9"
```


保存并运行 E2E 实际执行的示例：


```js title="openai-javascript.mjs"
import OpenAI from 'openai';

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

const client = new OpenAI({
  baseURL: requiredEnvironment('NEXUS_BASE_URL'),
  apiKey: requiredEnvironment('NEXUS_API_KEY'),
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: requiredEnvironment('NEXUS_MODEL'),
  messages: [{ role: 'user', content: 'Keep this request unchanged.' }],
  temperature: 0.37,
});

console.log(
  JSON.stringify({
    model: completion.model,
    content: completion.choices[0]?.message.content,
  }),
);
```


```sh title="Terminal"
node openai-javascript.mjs
```

Nexus 不改写 `model` 或 Provider Payload。显式选择另一条 ProviderConnection 时，必须改用该 Provider 接受的模型名。

## 6. Verify usage

回到同一 Workspace：

1. **Usage** 应显示所选 ProviderConnection、请求模型、WorkspaceAccess、Token、Quota Units、状态和 Request ID。
2. **Activity → Logs** 应把请求归因到 Provision 的 `externalUserId`。
3. **Activity → Audit** 应保留管理面操作，而不包含 Provider Key 或 Inference Key 明文。

## Check your work

| Check                 | Expected result                                                             |
| --------------------- | --------------------------------------------------------------------------- |
| Provider verification | Connection accepted；响应不返回 Provider Key 明文                           |
| User provisioning     | `WorkspaceAccess` 为可调用状态，并存在当前 QuotaPeriod                      |
| SDK response          | 返回 Provider 响应，`model` 保持原始值                                      |
| Gateway headers       | 包含 `x-nexus-request-id` 和 metering/quota 元数据                          |
| Usage                 | Invocation 与 UsageEvent 关联到同一用户、Plan、Period 和 ProviderConnection |

## What Nexus stored

Workspace 边界、加密 Provider Secret、不可变 ProviderConnection ID、WorkspacePlan/QuotaStrategy、WorkspaceAccess、Key Binding、QuotaPeriod，以及请求后的 Invocation、UsageEvent 和 Audit 事实。

## What the user received

一个 Gateway Base URL、一次性 Inference Key 和所选 Provider 接受的原始模型名。用户没有得到 Provider Key、Management Key 或任意上游 Host 的选择权。

## Troubleshooting

| Symptom        | Check first                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `401`          | 是否使用未撤销、未到期的 Inference Key，而不是 Provider/Management Key |
| `403` / `404`  | Key 对应的 WorkspaceAccess 是否可用，UUID 是否属于同一 Workspace       |
| `429`          | 当前 QuotaPeriod 的可用 Units 和重置时间                               |
| Provider error | ProviderConnection 验证状态、上游模型名及 Request ID；不要改写 Host    |

## Next steps

- 把 [Use my Nexus access](/docs/quickstarts/use-my-nexus-access) 交给应用用户。
- 比较 [JavaScript、Python 和 OpenCode](/docs/make-model-requests) 的受测接入方式。
- 在轮换前复核 [Credential model](/docs/give-users-access/credential-model)。

Source: https://nexus.microvoid.io/docs/quickstarts/add-nexus-to-product/index.mdx