WorkspaceAccess

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

Outcome

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

Credential and request boundary

Provider boundary

Developer Provider Secret
Written by the platform developer; never delivered to the application user.
Encrypted ProviderConnection
Stores one explicit upstream capability inside a Workspace.

Admin Plane

Application Backend
Uses a Management Key to configure resources and provision users.
Nexus Admin API
Creates User, WorkspaceAccess and QuotaPeriod.
Inference Key
Returned once and delivered to the trusted user client.

Data Plane

User SDK or Agent
Sends the Inference Key and an explicit connection UUID.
Nexus Gateway
Resolves Access and commits a Quota Reservation in PostgreSQL.
Workspace ProviderConnection
Supplies the selected Base URL and decrypted short-lived credential.
Model Provider
Receives the original provider path, model and payload.

Provider Secret 不到达最终用户；Admin Plane 管理配置与生命周期；Data Plane 只有在 PostgreSQL 中的 Access、Quota 和 Workspace-scoped ProviderConnection 校验全部成功后才调用 Provider。

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 用户：

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。完整授权必须解析：

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