> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 凭据管理

凭据管理用于集中配置和管控插件运行所需的认证信息（如 API Key、Access Token），支持“全局—工作空间”的多层级授权与使用控制。通过统一管理，企业能够在安全合规与灵活性之间取得平衡：IT 管理员在管理后台集中维护全局凭据，并可选择性地允许工作空间维护本地凭据。

## 1. 功能简介

凭据管理解决了以下常见问题：

* **重复配置**：多个工作空间需要使用相同凭据，如果各自维护，容易造成冗余和不一致。
* **安全风险**：凭据分散管理，增加泄露和滥用的风险，不符合企业安全要求。
* **治理难度**：缺少统一的策略控制，难以明确哪些工作空间可使用凭据，哪些插件允许自建凭据。

### 1.1 功能价值

* **集中化管理**：系统管理员在管理后台统一配置和维护凭据，分配到指定工作空间使用。
* **降低安全风险**：敏感信息集中治理，避免凭据散落在各个工作空间。
* **灵活可控**：支持允许或禁止工作空间自建凭据，并提供例外机制，兼顾安全与灵活性。
* **统一更新**：凭据更新或轮换时，只需在管理后台修改一次即可全局生效。

### 1.2 适用场景

* 企业 IT 部门统一管理模型供应商 API Key，并按需分配到业务团队的工作空间。
* 对生产环境插件（如数据库）要求全局统一配置，而对测试插件允许工作空间自建凭据。
* 需要为预定义模型和自定义模型配置不同的凭据，并在应用编排或模型供应商页面中灵活选择。

### 1.3 核心概念

**插件类型**

* 模型类插件：如 OpenAI、Claude、Gemini
* 工具类插件：如数据库、HTTP 调用器、Google Map
  **凭据类型**
* 工具类凭据：工具类插件运行所需的认证信息
* 模型类凭据（预定义模型、自定义模型）：模型类插件运行所需的认证信息
  **凭据层级**
* 全局凭据：由系统管理员在管理后台创建，分配给多个工作空间，工作空间内可引用但不可修改
* 工作空间凭据：由工作空间管理员或应用编排者在本工作空间内创建，仅对本工作空间可见，是否允许由凭据策略决定

## 2. 操作说明

### 2.0 快速开始

凭据管理的典型流程包括三个步骤：**创建全局凭据 > 分配到工作空间 > 在工作空间中引用**。以下示例以 OpenAI 插件为例：

1. **在管理后台创建凭据**
   管理后台 > 凭据管理 > 模型插件凭据 > 【添加凭据】
   选择 OpenAI 插件及版本，填写凭据名称和 API Key，保存。
2. **分配凭据到目标工作空间**
   在凭据列表中找到刚创建的凭据，点击【分配凭据】，选择目标工作空间并点击【分配】。
3. **在工作空间中引用凭据**
   进入目标工作空间 > 设置 > 模型供应商 > OpenAI > 配置
   在配置页面的凭据下拉框中，选择已分配的全局凭据。
   通过以上步骤，即可完成一次完整的凭据配置与使用流程。更复杂的场景（如工具类凭据、自定义模型、凭据策略设置），请参考后续小节的详细说明。
   ![](https://assets-docs.dify.ai/2025/09/c55a796a868770f82e6b42cf1effe150.png)

### 2.1 访问路径

* **管理后台**：管理后台 > 凭据管理
  可执行添加凭据、编辑凭据、分配凭据、删除凭据和凭据策略设置。
* **工作空间**：工具、工作空间 > 具体应用 > 编排，设置 > 模型供应商
  可查看被分配的全局凭据，在策略允许的情况下新建自定义凭据，并在工具、模型供应商或编排中选择使用。

### 2.2 凭据列表

在管理后台凭据管理页中，凭据列表按插件分组展示所有已创建的全局凭据，字段包括：

* 插件版本
* 凭据名称
* 模型（模型类插件适用）：展示当前凭据作用于预定义模型还是自定义模型
* 分配工作空间数（可悬停查看详细列表）
* 创建时间、更新时间
* 操作：详情、分配凭据、删除凭据

### 2.3 新增工具类凭据

在“工具类插件凭据”页面，可以为已安装的工具类插件新增凭据：

1. 点击【添加凭据】
2. 选择目标插件及版本（仅限已安装插件）
3. 填写凭据名称（在该插件下需唯一）
4. 根据插件要求填写凭据参数
5. 点击【保存】，系统会验证有效性
   保存成功后，默认未分配任何工作空间。可选择【现在分配】立即分配，也可稍后在凭据列表中分配。
   **常见提示**：

* **当前插件无需配置凭据，请重新选择插件**：所选插件不需要凭据
* **凭据验证失败**：参数错误或网络异常，应检查 API Key 和网络连通性
* **名称已存在**：凭据名称重复，应修改为唯一值
  ![](https://assets-docs.dify.ai/2025/09/1536da7ca9f5f09deee5a439f9dfdb1d.png)

### 2.4 新增模型类凭据

在“模型类插件凭据”页面，可创建预定义模型或自定义模型凭据：

1. 点击【添加凭据】
2. 选择模型类插件和版本
3. 选择模型类型：
   * **预定义模型**：填写凭据名称和参数
   * **自定义模型**：选择模型类型并填写模型名称，再填写凭据名称和参数
4. 点击【保存】，系统会验证有效性
   保存成功后，默认未分配任何工作空间，可根据提示分配，也可稍后分配。
   **常见提示**：

* **凭据验证失败**：检查供应商 API Key 或网络状态
* **名称已存在**：在该插件下名称重复，应修改为唯一值
  ![](https://assets-docs.dify.ai/2025/09/a2f87f646b67a2129b11c46300c09d2f.png)

### 2.5 编辑凭据

在凭据列表中点击【详情】，可修改凭据的名称、版本和参数。

* 插件类型不可修改
* 模型类凭据的“是否预定义模型”、“模型类型”和“模型名称”不可修改
* 切换版本时，兼容字段会自动迁移，不兼容字段需手动填写

### 2.6 分配凭据

在凭据列表中点击【分配凭据】，可选择目标工作空间进行分配。仅被分配的工作空间，才能在工具、模型供应商或编排中使用该凭据。
在凭据分配页面移除工作空间时，系统会检测该工作空间内是否存在应用正在引用该凭据。若存在，将列出受影响的应用，并提示移除后调用将失败。为确保应用正常运行，应先在工作空间内替换为其他凭据，再执行移除操作。

> **注意**：移除模型类凭据时，系统仅能检测工作空间是否使用了该凭据。由于模型凭据在工作空间层级生效，无法进一步追踪至具体应用。该规则对删除凭据操作同样适用。

![](https://assets-docs.dify.ai/2025/09/1808ca2c662c06e5cb5e97d7c56bd354.png)

### 2.7 删除凭据

点击【删除凭据】可以彻底移除凭据。系统会检查是否有应用正在引用该凭据。
若存在引用，系统会列出依赖情况，并提示删除后相关应用将无法正常调用插件。应在完成替换后，再执行删除操作。

### 2.8 配置凭据策略

凭据策略用于控制工作空间是否可以使用自定义凭据。典型场景包括：

* 支付类插件（如 PayPal、支付宝）仅允许使用管理后台配置的全局凭据；
* 禁止工作空间使用自定义凭据，强制其依赖全局凭据访问指定模型。
  在凭据策略设置页，可配置是否允许工作空间使用自定义凭据，并为特定插件设置例外：
* **允许**：工作空间可新建和使用自定义凭据
* **禁止**：工作空间自定义入口置灰，不可新建或使用
* **例外插件**：不受全局限制，可单独允许
  在保存策略时，系统会自动检测是否存在正在使用自定义凭据且与策略冲突的应用。若检测到冲突，将列出受影响的应用清单，并支持导出为 CSV。确认保存后，相关应用将无法正常调用插件。

> **注意**：对于模型类插件，系统仅能检测工作空间是否使用了相关凭据。由于模型凭据在工作空间层级生效，无法进一步追踪至具体应用。

![](https://assets-docs.dify.ai/2025/09/a9a96739b488b686ae8608cd9869d3aa.png)

### 2.9 工作空间中使用凭据

工作空间管理员和编排者可在以下位置使用凭据：

* **工具页面或模型供应商设置**：选择已分配的全局凭据
* **新建工作空间凭据（在策略允许时）**：点击【添加凭据】，填写参数并保存
* **编排应用**：在节点配置中选择凭据，或在允许时新建工作空间凭据
  当凭据策略禁止自定义凭据时，已有的工作空间凭据将显示为“自定义凭据当前不可用”，并禁止新增。
  若全局凭据被删除，则会提示“凭据已被删除”，此时需改用其他凭据或联系管理员调整配置。
  ![](https://assets-docs.dify.ai/2025/09/76e00dbb77e386061983ea6cc8c6e786.png)

## 3. 故障排查

* **凭据已被删除**：全局凭据已在后台移除。应切换为其他凭据，或联系管理员恢复。
* **凭据不可用**：可能因分配被移除，或后台关闭了工作空间自定义策略。应确认分配情况，必要时联系管理员调整。
* **凭据验证失败**：API Key 无效、参数错误或网络超时。应检查凭据参数和网络，并在必要时重新生成密钥。

## 4. 常见问题（FAQ）

### 为什么在工作空间中无法新建凭据？

作空间中创建凭据，取决于管理后台配置的凭据策略。若策略中禁止工作空间为特定插件使用自定义凭据，则在该工作空间中对应插件的“新建凭据”入口将被隐藏，仅可使用全局凭据。

### 全局凭据和工作空间凭据有什么区别？

全局凭据由后台统一维护，可分配给多个工作空间；工作空间凭据仅在单一工作空间可见，是否允许取决于凭据策略。

### 凭据策略中禁止工作空间使用特定插件的自定义凭据后，已有的自定义凭据会怎样？

在策略生效后，工作空间内已有的该插件自定义凭据将立即标记为“不可用”，无法继续使用或新增。相关应用只能切换为全局凭据。

### 为什么在凭据分配页面移除工作空间后，应用会失败？

在凭据分配页面移除工作空间后，该工作空间将失去对相应凭据的使用权。若应用仍在引用该凭据，将无法继续调用相关服务并产生错误。为避免影响应用运行，应先在应用中替换为新的凭据，再执行移除操作。

### 删除凭据和在凭据分配页面移除工作空间有什么区别？

* **删除凭据**：彻底移除该凭据，所有工作空间和应用的引用将立即失效。
* **在凭据分配页面移除工作空间**：仅影响被移除的工作空间，该空间内的应用将失去对该凭据的使用权，其它工作空间不受影响。

### 插件被卸载后，全局凭据还在吗？

当某个插件版本在所有工作空间中被彻底卸载后，对应的全局凭据不会被自动删除。此类凭据将保留在系统中，但不可继续编辑。
可以选择将凭据的插件版本切换为该插件的其他已安装版本，或直接删除该凭据。

## 5. 最佳实践

* **集中管理敏感凭据**：统一由后台配置全局凭据，避免敏感信息分散。
* **建立轮换机制**：凭据应定期更新，先添加替代凭据并分配，再替换使用，最后回收旧凭据。
* **删除或移除前导出清单**：确保依赖已替换，避免业务中断。
* **策略与例外结合**：一般允许工作空间自建，涉及敏感插件时关闭，仅对少数插件设置例外。
* **规范命名**：凭据命名应清晰区分预定义模型和自定义模型，方便维护和排查。
* **分工明确**：系统管理员负责全局策略与敏感操作；工作空间管理员负责应用内替换与选择。
* **先测试后上线**：在测试工作空间验证凭据和插件版本兼容性，再在生产环境中启用。