---
title: "API 密钥与权限"
description: "创建限定产品、功能和项目范围的组织 API 密钥。保存仅展示一次的完整密钥，按需轮换，并了解撤销的作用范围。"
image: "https://docs.sinecloud.dev/opengraph.png"
---

> 完整文档索引： https://docs.sinecloud.dev/zh-CN/llms.txt

# API 密钥与权限

组织 API 密钥用于从程序访问 Agents、Box、Powers 或 Gateway。控制台使用登录会话，不需要先创建密钥。只有当前组织的[所有者或管理员](/zh-CN/organizations/)可以创建、查看和撤销密钥。

## 创建密钥

1. 打开 [Console](https://sinecloud.dev/zh-CN/dashboard)，选择目标组织，进入“API 密钥”。产品的 API 页也可带入对应产品和项目范围。
2. 点击“创建 API 密钥”，填写便于识别用途的名称。
3. 勾选需要的一个或多个产品，逐个选择允许功能。
4. 选择“整个组织”或具体项目，并设置到期时间。
5. 创建后立即复制完整密钥，存入应用的机密配置或密钥管理服务。

**完整密钥只展示一次。** 关闭结果、离开页面或切换组织后，列表只能显示前缀。如果不再掌握完整密钥，应撤销它并创建新密钥。

## 产品与功能范围

| 产品 | 可授予功能 |
| --- | --- |
| [Agents](/zh-CN/products/agents/) | `agentRun`；按需增加 `browserRun`、`sandboxRun`。 |
| [Box](/zh-CN/products/box/) | `fileRead`；按需增加 `fileWrite`、`boxRun`。 |
| [Powers](/zh-CN/products/powers/) | `catalogRead`、`connectionRead`、`connectionWrite`、`toolRun`、`runRead`、`usageRead`。 |
| [Gateway](/zh-CN/products/gateway/) | `modelRead`、`modelInvoke`、`configRead`、`configWrite`、`usageRead`。 |

Agents 和 Box 分别以 `agentRun`、`fileRead` 为基础功能。Powers 和 Gateway 可以选择任意非空功能集合；例如 Gateway 只调用模型时可仅授予 `modelInvoke`，需要查询模型列表时再加 `modelRead`。

同一密钥可访问多个产品，但每个产品单独授权。Powers 的 `usageRead` 不授予 Gateway 用量权限，Agents 授权也不允许直接访问 Box。密钥功能不会扩大组织权益，`browserRun` 不等于当前环境提供完整浏览器自动化。

## 项目范围

- **整个组织**：所选产品在当前、未来项目及无项目范围的资源都在密钥范围内，仍受实际权限限制。
- **具体项目**：所有勾选产品均限制为该项目；请求参数或请求头不能扩大这个范围。

为不同应用分别创建密钥有助于独立撤销和收紧权限。[Gateway 组织预算管理](/zh-CN/products/gateway/)等功能还可能要求组织范围密钥。

## 使用与轮换

使用产品 API 页提供的地址，并通过 `Authorization: Bearer` 请求头传递组织 API 密钥。不要将密钥放入公开网页、仓库、URL 或日志；供应商 BYOK 凭据应保存在产品连接设置中，不能替代组织 API 密钥。

使用 `https://sinecloud.dev` 加上文档中的完整路径，将资源 ID 替换为实际值。

轮换时先创建替代密钥，更新应用配置，再撤销旧密钥。创建结果因网络故障不确定时，先查看列表并沿用原创建草稿恢复；无法取回密钥时撤销后重建，不要反复提交新的创建请求。

## 撤销与失效

在列表中打开“权限与详情”核对用途，确认撤销。撤销不可恢复，同时阻断这把密钥的所有产品授权；历史账务记录仍保留。

到期、创建者被封禁或失去组织管理角色，都会阻止新的请求。退出后重新加入或重新获得管理员角色不会恢复旧密钥。组织或资源暂停、到期也可能阻断执行。

撤销密钥**不会自动取消已开始的执行或已建立的事件订阅**。需要停止任务时，还应使用对应产品的取消或暂停操作，并在[用量与账务](/zh-CN/billing/)中核对结果。

来源: https://docs.sinecloud.dev/zh-CN/api-keys/index.mdx