# 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]

在 **组织 > Developer > API Key** 中创建组织键。组织键使用 `gtx-org-` 前缀，并且可配置自定义权限集。

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

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

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

对于调用 [Context Management API](/docs/platform/openapi/reference/context-management/list-groups) 的自动化，请将 **上下文** 设置为 **Read** 或 **Write** (`org:context:read` / `org:context:write`) 。项目键无法管理上下文组。

对于调用 [创建项目 API Key](/docs/platform/openapi/reference/project/create-api-key) 的自动化，请将 **项目 API Key** 设置为 **Write**。如需为某个组织中的项目创建键，请使用该组织下具备所需权限的组织键。项目键无法创建其他键。

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

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

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

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

项目密钥支持以下资源：

| Resource                | Read      | Write or enabled |
| ----------------------- | --------- | ---------------- |
| **文件**               | 读取项目文件和翻译 | 上传源内容并写入翻译后的文件   |
| **上下文**             | 读取项目上下文   | 管理项目上下文          |
| **运行时翻译** | 不适用       | 按需翻译内容           |
| **Translation queue**   | 不适用       | 将文件翻译任务加入队列      |
| **项目“设置”**              | 不适用       | 更新项目“设置”         |

对于本地按需翻译，任何拥有 `project:translations:generate` 权限的项目密钥均可使用，包括完全访问权限的键。为降低风险，建议单独创建一个使用 **Custom** 权限的键：将 **运行时翻译** 设为 **Enabled**，其余资源保持 **None**。对于文件翻译流水线，请授予 **文件 > Write** 和 **Translation queue > Enabled**；如果流水线还会生成上下文，请另外添加 **上下文 > Write**。

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

在大多数 SDK 和 CLI 工作流中，请将该键与你的 project 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]

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

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

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

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

撤销不再使用的键，并在轮换凭据时创建新的替代键。

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

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

请在 **Project > 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.