---
title: "Credential model"
description: "Keep Provider Secrets, Management Keys, and Inference Keys in their intended plane, audience, and lifecycle."
---

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

# Credential model

## Outcome

你可以选择正确的 Credential，安全交付 Inference Key，并判断一次请求为何不能跨越 Admin/Data Plane。

| Credential      | Plane             | Owner or recipient         | Accepted route | Storage rule                                              |
| --------------- | ----------------- | -------------------------- | -------------- | --------------------------------------------------------- |
| Provider Secret | Provider boundary | 平台开发者写入 Nexus       | 仅用于上游认证 | 加密保存，永不交付最终用户。                              |
| Management Key  | Admin             | 应用后端或获授权的操作人员 | `/admin/v1/*`  | Better Auth 保存 Hash；明文仅创建时返回。                 |
| Inference Key   | Data              | 应用用户或可信 User Agent  | `/providers/*` | Better Auth 保存 Hash，并通过 ApiKeyBinding 解析 Access。 |

三种 Credential 不能互换。Management Key 即使验证成功也不能调用 Gateway；Inference Key 不能进入 Admin API；Provider Secret 不能出现在任何 Nexus 客户端请求中。

## Inference Key resolution

```text
Authorization: Bearer <NEXUS_INFERENCE_KEY>
→ Better Auth verify with configId = inference
→ apiKeyId
→ ApiKeyBinding
→ WorkspaceAccess
→ Workspace
```

Key metadata 只用于展示或诊断，不是 Workspace、Plan 或 Quota 的授权事实。

## Plaintext is a one-time event

Management 和 Inference Key 明文只在创建响应中显示一次。之后的列表仅返回 ID、名称、Prefix、状态、过期时间和最后使用时间。Provider Secret 创建或轮换后也只能读取脱敏 Preview。

应用后端应通过服务器到服务器的私密渠道交付 Inference Key，并避免：

- 写入 Git、静态配置或客户端 Bundle。
- 放入 URL、Analytics、错误上报或普通日志。
- 通过不可信浏览器持久化存储长期 Bearer Key。
- 把 Key 明文保存为用户 Profile metadata。

## Rotation changes the credential, not the grant

Inference Key 轮换创建新 Credential 与 ApiKeyBinding，再撤销旧 Key。它不会复制 WorkspaceAccess、变更 Plan、重置 QuotaPeriod 或删除历史 Usage。

Provider Secret 轮换只更新所选 ProviderConnection 的上游认证材料。Connection UUID 和用户 Inference Key 保持不变。

## Browser and mobile boundary

长期 Bearer Key 不适合不可信浏览器和移动端。Session 换取短期 Data Token 是后续能力，在正式发布前不要把它当成现有稳定接口；MVP 的公开示例以可信服务端或受控 User Agent 为边界。

## Next steps

- [WorkspaceAccess](/docs/give-users-access/workspace-access)
- [Key, Access, and Period time](/docs/give-users-access/time-boundaries)

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