---
title: "WorkspaceAccess"
description: "Understand the data-plane relationship that grants one application user a plan, lifetime, quota, and inference keys."
---

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

# WorkspaceAccess

## Outcome

你可以为应用用户建立正确的数据面授权关系，并能说明为什么 Organization Member、WorkspaceAccess 和 API Key 不可互相替代。

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

## Member is not Access

| Relationship        | Plane | What it grants                                        |
| ------------------- | ----- | ----------------------------------------------------- |
| Organization Member | Admin | Console 与 Admin API 的组织权限。                     |
| WorkspaceAccess     | Data  | 在一个 Workspace 中按 Plan、有效期和 Quota 调用模型。 |

同一个 Better Auth User 可以同时拥有两种关系，但最终用户不会因为获得 WorkspaceAccess 而自动成为 Organization Member，控制面成员也不会自动获得数据面额度。

## What WorkspaceAccess owns

一条 WorkspaceAccess 连接 `User + Workspace + WorkspacePlan`，并保存：

- Workspace 内的 `externalUserId`。
- `PENDING`、`ACTIVE`、`SUSPENDED`、`EXPIRED` 或 `REVOKED` 状态。
- `accessStartsAt` 和可选 `accessEndsAt`。
- 一个或多个 ApiKeyBinding。
- 按周期创建的 QuotaPeriod 与历史 Invocation。

它不保存 Provider Secret，也不复制 API Key 明文。

## Provisioning is idempotent

应用后端以 `(workspaceId, externalUserId)` 为业务唯一键 Provision 用户：

```text
create or find Better Auth User
→ upsert WorkspaceAccess
→ bind WorkspacePlan
→ ensure current QuotaPeriod
→ create Inference Key + ApiKeyBinding
→ return new Key plaintext once
```

Email 不能单独作为 Workspace 用户幂等键。重复业务请求必须使用相同 Idempotency Key，并遵守 API 对 Key 明文不可重放的约束。

## Status changes

| Action      | New requests                            | Existing facts                            |
| ----------- | --------------------------------------- | ----------------------------------------- |
| Suspend     | 在 Provider 前拒绝。                    | Access、Period、Usage 与 Audit 保留。     |
| Activate    | 在其他时间边界有效时恢复。              | 不创建新 User 或重置 Quota。              |
| Renew       | 更新 Access 周期并幂等创建后续 Period。 | 不要求更换 Key。                          |
| Change plan | 更新 Access 的 Plan。                   | 已 ACTIVE Period 继续使用自己的策略快照。 |
| Revoke      | 永久拒绝该 Access 的新请求。            | 历史事实保留。                            |

## Connection scope

有效 WorkspaceAccess 默认可使用同一 Workspace 的全部 ACTIVE ProviderConnection，并共享 Access 维度的 Quota。Connection 仍由每个请求 Base URL 中的 UUID 明确选择；如需严格隔离上游，使用不同 Workspace 或受限的上游 Provider Secret。

## Authorization path

Gateway 不信任 Key metadata 中的 `workspaceId` 或 `planId`。完整授权必须解析：

```text
verified Inference Key ID
→ ACTIVE ApiKeyBinding
→ ACTIVE WorkspaceAccess
→ active QuotaPeriod
→ Workspace-scoped ProviderConnection
→ committed QuotaReservation
```

## Next steps

- [Credential model](/docs/give-users-access/credential-model)
- [Key, Access, and Period time](/docs/give-users-access/time-boundaries)
- [Quota periods](/docs/control-plans-and-quota/quota-periods)

Source: https://nexus.microvoid.io/docs/give-users-access/workspace-access/index.mdx