---
title: "Core concepts"
description: "Build a stable mental model for Workspace, ProviderConnection, User Access, credentials, plans, and quota."
---

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

# Core concepts

## Outcome

你可以用一张关系图定位每个 Nexus 概念，并避免把身份、Access、Credential、Plan 和 Quota 混为同一件事。

```text
Organization ── Member ── User                 Admin Plane
                         │
Workspace ── WorkspaceAccess ── User           Data Plane
    │              │
    │              ├── WorkspacePlan ── PlanStrategyBinding ── QuotaStrategy
    │              ├── QuotaPeriod ── QuotaReservation
    │              └── ApiKeyBinding ← Inference Key
    │
    └── ProviderConnection[] ← providerConnectionId in Gateway Base URL
```

## Configuration boundary

### Workspace

应用或环境的配置与隔离边界。ProviderConnection、WorkspacePlan、PlanStrategy、WorkspaceAccess、Quota 和 Usage 都属于一个 Workspace。

### ProviderConnection

Workspace 内一条明确的上游能力连接，包含服务生成的不可变 UUID、上游 Base URL、Protocol Profile、状态和加密 Provider Secret。多条 Connection 表示多个可显式选择的目标，不代表自动选择。

## Identity and access

### Better Auth User

共享的身份记录。它可以通过 Organization Member 进入控制面，也可以通过 WorkspaceAccess 进入数据面；两种关系独立存在。

### WorkspaceAccess

一个 User 在一个 Workspace 的数据面使用权，绑定当前 WorkspacePlan、Access 状态和有效期。它不是 API Key，也不是 Organization Membership。

### ApiKeyBinding

把一把 Inference Key 的 Better Auth Key ID 指向 WorkspaceAccess。Gateway 的授权解析必须经过这条数据库关系。

## Plans and quota

### WorkspacePlan

Free、Pro 等稳定产品套餐。Access 绑定 Plan；Plan 通过带生效区间的 PlanStrategyBinding 启用类型化策略。

### QuotaStrategy

MVP 唯一实现的 Plan Strategy，定义周期 Quota Units、整数 PPM 倍率、重置周期和最大输出上限。它不包含模型列表、Provider 成本或支付售价。

### QuotaPeriod

某条 WorkspaceAccess 在一个时间区间内的额度快照。它保存 Granted、Reserved、Consumed 和创建时的策略快照。

### QuotaReservation

请求进入 Provider 前原子创建的额度预留。它处理并发和 Streaming，并最终进入 `SETTLED`、`RELEASED` 或 `EXPIRED`。

## Three invariants to remember

1. Inference Key 通过 `ApiKeyBinding → WorkspaceAccess → Workspace` 解析。
2. Gateway 用 `(workspaceId, providerConnectionId)` 读取连接，客户端不能指定上游 Host。
3. `ApiKey.expiresAt`、`WorkspaceAccess.accessEndsAt` 与 `QuotaPeriod.periodEnd` 是三个独立时间边界。

## Next steps

- [Glossary](/docs/glossary)
- [Credential model](/docs/give-users-access/credential-model)
- [Workspace plans](/docs/control-plans-and-quota/workspace-plans)

Source: https://nexus.microvoid.io/docs/core-concepts/index.mdx