# General Translation Platform: API 键
URL: https://generaltranslation.com/zh/docs/platform/dashboard/reference/api-keys.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 为应用、本地开发和自动化创建并管理项目和组织 API 键。API 键参考。

API 键用于让你的应用、CLI 和自动化访问 General Translation 时完成身份验证。请使用既能满足工作流需求、层级又尽可能小的键。

## 键层级 [#key-scopes]

General Translation 支持两种 API Key 层级：

* **Organization 键** 用于 Organization 层级的自动化。可用于组织层级的自动化任务，或需要在 Organization 内跨多个项目运行的工作流。
* **项目 键** 用于单个项目。可用于服务器端环境、本地开发以及项目层级的工具。切勿将其包含在已部署的浏览器或移动应用 bundle 中。

在 仪表板 中，两种层级均支持 **All** 或 **Custom** 权限。**All** 会授予你在该层级内可委派的所有权限。**Custom** 允许你选择更小的权限集合；至少需要选择一项权限。你只能授予自己已拥有的权限。

## 创建组织密钥 [#create-organization-keys]

在 **组织 &gt; Developer &gt; API 密钥** 中创建组织密钥。组织密钥使用 `gtx-org-` 前缀，并且可配置自定义权限集。

在这些仪表板控件中，权限按资源分别配置。`Write` 包含 `Read`。

| 资源                    | 读取         | 写入 或启用后                 |
| --------------------- | ------------ | ----------------------- |
| **项目创建**              | 不适用          | 在组织中创建新项目               |
| **项目 API 密钥**         | 查看项目的 API 密钥 | 查看、创建和删除项目 API 密钥       |
| **文件**                | 读取项目文件和译文    | 上传源内容并写入翻译后的文件          |
| **上下文**               | 读取项目和组织的上下文  | 管理上下文组、词汇表和自定义提示词       |
| **组织资源**              | 不适用          | 上传和替换组织内所有项目共享的资源 (如字体) |
| **运行时翻译**             | 不适用          | 按需翻译内容                  |
| **Translation queue** | 不适用          | 将文件翻译任务加入队列以进行后台处理      |
| **项目“设置”**            | 不适用          | 更新默认区域设置和 CDN 交付等项目“设置” |

为调用 [创建项目](/docs/platform/openapi/reference/projects/create-project) 端点 的自动化 启用 **项目创建**。其 `org:projects:create` 权限也允许创建启用了 CDN 交付的项目；只有后续需要更新设置时，才需要 **项目“设置”** (`project:write`) 。仅为每个密钥授予其所需的权限。

对于调用 [Context Management API](/docs/platform/openapi/reference/context-groups/list-context-groups) 的自动化，请将 **上下文** 设置为 **读取** 或 **写入** (`org:context:read` / `org:context:write`) 。具备此权限的组织密钥可操作组织内的所有上下文组。[项目密钥](#create-project-keys)只能访问已分配给其所属项目的组，且无法创建、更新、删除、分配或取消分配组。

对于为 Lottie 翻译上传字体的自动化 (例如 CLI [`fonts`](/docs/cli/reference/config#fonts) 同步) ，请将 **组织资源** 设置为 **写入** (`org:assets:write`) 。项目密钥无法上传字体。

对于调用 [创建项目 API 密钥](/docs/platform/openapi/reference/api-keys/create-project-api-key) 或 [删除项目 API 密钥](/docs/platform/openapi/reference/api-keys/delete-project-api-key) 的自动化，请将 **项目 API 密钥** 设置为 **写入**。只需 **读取** 权限即可[列出](/docs/platform/openapi/reference/api-keys/list-project-api-keys)或[获取](/docs/platform/openapi/reference/api-keys/get-project-api-key)项目的密钥，但结果绝不会包含密钥的机密值。如需为某个组织中的项目创建密钥，请使用该组织下具备所需权限的组织密钥。项目密钥无法列出、创建或删除密钥。

通过 [HTTP API](/docs/platform/openapi/reference/api-keys/create-project-api-key) 创建密钥时，可以显式选择权限；若不指定，则会授予你可委派的全部项目权限。与仪表板控件不同，通过 HTTP 显式授予的 写入 权限不包含 读取。

## 创建项目密钥 [#create-project-keys]

在 **项目 &gt; API 密钥** 中创建项目密钥。新键以 `gtx-api-` 开头，可在开发、预发布 和生产环境中使用。键的权限决定了它能执行哪些操作。

1. 创建键，并输入一个具有描述性的 **名称**。
2. 在 **权限** 下选择 **All** 或 **Custom**。
3. 若选择 **Custom**，请为每个资源指定所需的访问权限。
4. 选择 **Create**，然后立即复制完整键，并将其保存到环境变量或密钥管理器中。

项目密钥支持以下资源：

| Resource              | 读取          | 写入 or enabled            |
| --------------------- | ------------- | --------------------------- |
| **文件**                | 读取项目文件和译文     | 上传源内容并写入翻译后的文件              |
| **上下文**               | 读取分配给该项目的上下文组 | 生成上下文，以及编辑分配给该项目的上下文组并调整其顺序 |
| **运行时翻译**             | 不适用           | 按需翻译内容                      |
| **Translation queue** | 不适用           | 将文件翻译任务加入队列                 |
| **项目“设置”**            | 不适用           | 更新项目“设置”                    |

拥有 **上下文** 权限后，项目密钥可针对分配给其所属项目的上下文组调用 [Context Management API](/docs/platform/openapi/reference/context-groups/list-context-groups)。**读取** (`project:context:read`) 可列出这些组，并读取和导出其词汇表与自定义提示词。**写入** (`project:context:write`) 还可编辑和导入这些内容、调整组的顺序以及生成上下文。项目密钥无法创建、更新、删除、分配或取消分配上下文组，这些操作需要使用组织密钥。对于未分配给该键所属项目的组，返回的 `403` 与访问不存在的组时相同。

对于本地按需翻译，任何拥有 `project:translations:generate` 权限的项目密钥均可使用，包括完全访问权限的键。为降低风险，建议单独创建一个使用 **Custom** 权限的键：将 **运行时翻译** 设为 **Enabled**，其余资源保持 **None**。对于文件翻译流水线，请授予 **文件 &gt; 写入** (已包含 读取)、**Translation queue &gt; Enabled** 和 **上下文 &gt; 写入**。[`gt translate`](/docs/cli/reference/commands/translate) 会在将翻译加入队列之前生成上下文，因此缺少 **上下文 &gt; 写入** 时会执行失败。如果改为通过 HTTP API 或 [`gt api-key create`](/docs/cli/reference/commands/api-key-create) 创建键，请显式申请 `project:files:read`、`project:files:write`、`project:translations:enqueue` 和 `project:context:write`，因为在这两种方式下，写入 并不包含 读取。

SDK 设置 `devApiKey` 和环境变量 `GT_DEV_API_KEY` 仍可启用开发翻译和 hot reload。请在该设置中填入具有 运行时翻译 权限的项目密钥。设置名称并不意味着存在单独的键类型。

在大多数 SDK 和 CLI 工作流中，请将该键与你的 项目 ID 搭配使用：

```bash
GT_API_KEY=gtx-api-...
GT_PROJECT_ID=...
```

如需以账户身份通过 CLI 访问，请使用 [`gt login`](/docs/cli/reference/commands/login)。如需通过 CLI 创建明确指定权限的项目密钥，请使用 [`gt api-key create`](/docs/cli/reference/commands/api-key-create)。

## 管理键 [#manage-keys]

使用便于理解的名称，方便后续识别键。

打开项目或组织的键列表以查看现有键。键列表会显示：

* **名称** 和 **键**，其中键为便于识别的截断形式
* **权限**，适用于项目密钥和组织密钥
* **创建时间**，键的生成时间
* **上次使用时间**，键最近一次使用的时间

如果拥有管理键的权限，可使用 **Edit key** 重命名键或更新其权限，使用 **删除** 撤销该键。完整密钥仅在创建键时显示一次。

撤销不再使用的键，并在轮换凭据时创建新的替代键。已删除的键通常会立即失效，最迟不超过 10 分钟。

如需通过自动化流程轮换项目密钥，请先[创建](/docs/platform/openapi/reference/api-keys/create-project-api-key)替代密钥，将工作流切换到新密钥，再按 ID [删除](/docs/platform/openapi/reference/api-keys/delete-project-api-key)旧密钥。这两个调用都需要一个将 **项目 API 密钥** 设置为 **写入** 的组织密钥。

## 已有的开发密钥 [#existing-keys]

已有的 `gtx-dev-` 键将继续作为项目键进行认证。此前默认仅具备运行时权限的键现在会获得默认的项目权限，包括文件、上下文、Translation queue 和项目“设置”。其他自定义权限组合保持不变。

请在 **Project &gt; API Keys** 中审校已有的键。对于本地开发，我们建议将其权限限制为 **Runtime translation**，或替换为新的仅运行时权限的键。拥有完整访问权限的键仍然可用，但 `gtx-dev-` 前缀不再代表权限受限。切勿将这些键打包进部署的客户端 bundle 中。

## 安全实践 [#security-practices]

* 切勿将键提交到版本控制系统。
* 无论权限如何，切勿将任何 API Key 打包进已部署的浏览器或移动应用 bundle 中。已部署的凭据应存放在服务器端环境变量或密钥管理器中。
* API Key 可用于仅由本地开发服务器提供的客户端代码中。完全访问权限的项目键虽然可用，但我们建议将本地开发键限制为 **运行时翻译** (`project:translations:generate`) ，以尽量降低风险。
* 将键存储在环境变量或密钥管理器中。
* 开发、预发布和生产环境应使用不同的键。
* 定期轮换键。
* 吊销不再使用的键。
* 优先采用能满足集成需求的最小层级。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.
