---
title: "How Nexus works"
description: "Follow configuration, provisioning, admission, provider dispatch, streaming settlement, and audit across the two planes."
---

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

# How Nexus works

## Outcome

你将能从 Provider Secret 一直追踪到一次确定结算的模型请求，并知道每一步由哪一个平面和哪一类事实负责。

### Credential and request boundary

1. **Developer Provider Secret** → encrypted `ProviderConnection`; it never reaches the application user.
2. **Application Backend** → Management Key → Nexus Admin API → `User + WorkspaceAccess`.
3. **Nexus Admin API** → one-time Inference Key → User SDK or Agent.
4. **User SDK or Agent** → Inference Key + explicit `providerConnectionId` → Nexus Gateway.
5. **Nexus Gateway** → PostgreSQL Access/Quota decision → selected ProviderConnection → Model Provider.

The Admin Plane owns configuration and lifecycle. The Data Plane accepts an Inference Key and an explicit connection UUID. PostgreSQL Access and Quota facts decide whether the Provider is called.

## 1. Configure capacity in the Admin Plane

Organization Member 或应用后端通过 Console、Admin API 或 Management SDK：

1. 创建 Workspace。
2. 创建 ProviderConnection；Nexus 生成不可变 UUID，并加密 Provider Secret。
3. 创建 WorkspacePlan，发布 QuotaStrategy，并通过 PlanStrategyBinding 绑定两者。

这些操作不进入 Gateway 请求热路径。

## 2. Provision an application user

应用后端按 `(workspaceId, externalUserId)` 幂等 Provision 用户。Nexus 创建或查找 Better Auth User，创建 WorkspaceAccess 和当前 QuotaPeriod，再签发只显示一次明文的 Inference Key。

```text
Better Auth User
└── WorkspaceAccess → WorkspacePlan → QuotaPeriod
    └── ApiKeyBinding ← Inference Key
```

## 3. Resolve and reserve before dispatch

用户 SDK 把 Inference Key 放在 `Authorization`，把不可变 `providerConnectionId` 放在 Gateway Base URL。Gateway 的准入顺序是：

```text
verify Inference Key
→ resolve ApiKeyBinding → WorkspaceAccess → Workspace
→ check Key, Access and QuotaPeriod time boundaries
→ resolve ACTIVE ProviderConnection by (workspaceId, providerConnectionId)
→ reserve Quota in PostgreSQL
→ call the Provider
```

任何准入步骤失败都不会调用 Provider。客户端不能提供上游 Host，也不能使用另一 Workspace 的 Connection ID。

## 4. Preserve the provider request

Gateway 将 Connection ID 后的完整 Path、Query、Method 和 Body 安全追加到 ProviderConnection 的 Base URL。客户端的 Nexus Authorization 被消费，并替换为已保存的 Provider Secret；`model` 和 Provider 自有字段原样发送。

## 5. Stream and reach one terminal result

普通响应、SSE 完成、Provider 错误、超时和客户端断开都会进入幂等终态：

- `SETTLED`：按可证明 Usage 扣除实际 Quota Units。
- `RELEASED`：没有可计量交付时释放预留。
- `EXPIRED`：恢复任务处理超时的 ACTIVE Reservation。

## 6. Keep authorization truth local

PostgreSQL 是 Access、Quota Reservation 和 Usage settlement 的事实源。Stripe、Creem、Queue、Cache 或 Analytics 不会绕过这条授权链；支付系统只异步投影 Access 和 Period 事实。

## Next steps

- [Provider connections](/docs/connect-model-capacity/provider-connections)
- [WorkspaceAccess](/docs/give-users-access/workspace-access)
- [Reserve, settle, and release](/docs/control-plans-and-quota/reserve-settle-release)

Source: https://nexus.microvoid.io/docs/how-nexus-works/index.mdx