# 令牌管理

> [!WARNING]
> 此功能包含在 Team & Enterprise 套餐中。

Tokens Management 允许组织管理员监督其组织内的访问令牌，确保对组织资源的安全访问。

> [!NOTE]
> 当令牌管理策略生效时，关于成员体验——包括如何检查令牌状态、预期会出现哪些错误，以及拒绝和撤销操作如何影响令牌——请参阅 [具有令牌管理策略的组织中的令牌](./security-tokens#tokens-in-organizations-with-token-management-policies)。

## 查看和管理访问令牌

令牌列表功能会显示您组织内的所有访问令牌。管理员可以：

- 监控令牌使用情况并识别或防范潜在的安全风险：
  - 对私有资源的未授权访问（“泄露”）
  - 过于宽泛的访问范围
  - 次优的令牌卫生状况（例如，长时间未轮换的令牌）
- 识别未激活或未使用的标记

    
    

细粒度令牌会显示其具体的权限：

    
    

已吊销的令牌默认在列表中隐藏。使用列表上方的 **显示已吊销的令牌** 开关可将其包含在视图中。

对于任何已吊销的令牌，无论组织的令牌策略如何，都会显示 **REVOKED** 状态徽章。**PENDING**、**APPROVED** 和 **DENIED** 徽章仅出现在启用了“需要管理员批准”策略的组织中，因为这些状态仅由审批流程创建。

## 令牌策略

Team & Enterprise 组织管理员可以强制实施以下策略：

| **策略**                                        | **无范围（读/写）访问令牌** | **细粒度标记**                                     |
| ------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------- |
| **允许通过用户访问令牌访问（默认）** | 已授权                              | 已授权                                                  |
| **仅通过细粒度令牌访问**           | 未授权                            | 已授权                                                  |
| **需要管理员批准**                | 未授权                            | 未经批准则未授权（管理员创建的除外） |

    
    

## 审查令牌授权

当令牌策略设置为“Require administrator approval”时，组织管理员可以审查所有访问组织所有资源的细粒度令牌的详细信息，并批准或拒绝访问。当新令牌进入待处理状态时，最多 50 位已确认电子邮件地址的组织管理员将收到通知，其中包含指向令牌审查页面的直接链接。当令牌被自动批准时（例如，因为创建者是组织管理员），不会发送通知。

- **Pending** 令牌正在等待管理员的决定
- **已批准**令牌已获授权并处于激活状态
- **Denied** 令牌已被阻止访问组织资源

当令牌被批准或拒绝时，令牌所有者会收到一封电子邮件通知。

拒绝并非永久性的：被拒绝的令牌之后可以由管理员批准，从而恢复其访问权限。同样，已批准的令牌也可以随时被拒绝，这将立即移除其基于批准的访问权限。

> [!NOTE]
> 当启用“需要管理员批准”策略时，Token 名称仅对管理员可见。

### 被屏蔽时成员看到的内容

令牌处于待处理或被拒绝状态的成员在访问组织资源时会收到 `403` 错误：_"根据组织令牌策略，您的令牌需要获得组织批准后才能访问此资源。"_

待处理和被拒绝两种状态的错误提示相同。要查看状态，成员可以导航到相应令牌的编辑页面。组织管理员的令牌管理设置页面会显示所有成员令牌的状态徽章。

    
    

## 拒绝与撤销

管理员有两种方式可以移除令牌对组织的访问权限：

| **方面**          | **拒绝**                                   | **撤销**                                                    |
| ------------------- | ------------------------------------------ | ------------------------------------------------------------- |
| **计划**            | 团队与企业                          | 企业版套餐及以上                                     |
| **范围**           | 在审批工作流中运行      | 与令牌策略无关                               |
| **效果**          | 阻止或移除基于审批的访问    | 强制移除访问权限，无论策略或令牌状态如何 |
| **可逆？**     | 是的——被拒绝的 token 之后可以被批准 | 不 — 即使策略发生变化，已吊销的状态仍然会持续存在       |
| **在其他位置标记** | 在组织外部无影响                  | 在组织外部无影响                                     |

在审批工作流中管理访问权限时，请使用 **deny**（令牌将过渡到 `denied` 状态，之后可以重新批准）。当您需要永久切断令牌对组织的访问权限时，请使用 **revoke**。

## 通过 API 列出 Token

在设置界面中显示的令牌列表也可以通过编程方式获取：

```bash
# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
curl -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \
  "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens"
```

响应是一个成员访问令牌数组。有关完整的架构，请参阅 OpenAPI 参考：GET /api/organizations//settings/tokens

默认情况下，已吊销的令牌会被隐藏；传入 `q=status:all` 即可将其包含在内，类似于 UI 中的 **显示已吊销的令牌** 开关。

## 撤销令牌

> [!WARNING]
> 此功能包含在企业版及以上套餐中。

组织管理员可以从令牌详情页面撤销任何成员的访问令牌。无论组织是否使用“需要管理员批准”策略，都可以执行撤销操作。被撤销的令牌将无法再访问该组织的资源，但在其他位置仍可正常使用。令牌所有者在令牌被撤销时会收到电子邮件通知。

即使组织的令牌策略随后被更改或禁用，已吊销的令牌仍保持吊销状态。在组织级别，吊销是永久性的——没有撤销吊销的操作。如果成员需要恢复访问权限，他们必须删除已吊销的令牌并创建一个新的令牌。如果组织使用“需要管理员批准”策略，新令牌将处于待处理状态，并需要管理员批准。

令牌已被撤销的成员将收到 `403` 错误，并显示以下消息：_"您的令牌已被组织管理员撤销，您无法再访问组织资源。请联系他们以获取更多信息。"_ 无论组织是否使用“需要管理员批准”策略，都会显示此消息。

### 通过 API 撤销

管理员还可以通过其令牌 ID 以编程方式撤销令牌。这在需要立即撤销令牌的自动化工作流中非常有用。

```bash
# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
# TOKEN_ID is the 24-character id shown on the org token settings page (or returned by the tokens listing API)
curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/${TOKEN_ID}/revoke" \
  -H "Authorization: Bearer ${ADMIN_HF_TOKEN}"
```

管理员无法撤销自己的令牌：如果请求中的令牌 ID 与用于身份验证的令牌相匹配，该请求将被拒绝并返回 `403` 错误。

> [!NOTE]
> 此端点仅撤销该令牌对您组织的访问权限；该令牌对其所有者的其他资源仍然有效。若要使泄露的令牌在所有位置均失效，请改用 [`POST /api/credentials/revoke`](./security-tokens#revoking-a-leaked-token)，该端点无需身份验证，并接受一批原始令牌值。

## 编程式令牌签发

> [!WARNING]
> 此功能包含在企业版及以上套餐中。

对于需要以编程方式为组织成员签发访问令牌的组织（例如用于内部平台、CI/CD 流水线或自定义集成），请参阅 [OAuth Token Exchange](./oauth#token-exchange-for-organizations-rfc-8693)。此企业版功能允许您的后端服务为组织成员签发具有作用域的令牌，而无需用户进行交互式授权。

## 服务账号

> [!WARNING]
> 此功能包含在企业版及以上套餐中。

对于由组织而非个人成员拥有的自动化访问权限，管理员可以创建 [Service Accounts](./enterprise-service-accounts) 并颁发细粒度令牌，其作用范围限定为组织的资源。