# General Translation Platform: API-ключи
URL: https://generaltranslation.com/ru/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-ключей:

* **ключи организация** для автоматизации на уровне организация. Используйте их для автоматизации на уровне организации или рабочий процессs, которым нужен доступ к нескольким проектам в рамках организация.
* **ключи проекта** для одного проекта. Используйте их в server-окружениях, при локальной разработке и в инструментах в области проекта. Никогда не включайте их в развернутые browser- или мобильные бандлы приложения.

В Dashboard обе области поддерживают разрешения **All** или **Custom**. **All** выдает все разрешения, которые вы можете делегировать в рамках этой области. **Custom** позволяет выбрать меньший набор; выберите хотя бы одно разрешение. Вы можете выдавать только те разрешения, которыми обладаете сами.

## Создание ключей организация [#create-organization-keys]

Создайте ключи организация в разделе **организация &gt; Developer &gt; Ключи API**. Ключи организация используют префикс `gtx-org-` и могут быть настроены с собственным набором разрешений.

В этих элементах управления Dashboard разрешения настраиваются отдельно для каждого ресурса. `Write` включает `Read`.

| Ресурс                  | Чтение                                 | Write or enabled                                                                  |
| ----------------------- | -------------------------------------- | --------------------------------------------------------------------------------- |
| **Создание проекта**    | Неприменимо                            | Создание новых проектов в организация                                             |
| **Ключи API проекта**   | Просмотр ключей API проектов           | Просмотр, создание и удаление ключей API проекта                                  |
| **Файлы**               | Чтение файлов проекта и переводов      | Загрузка исходного содержимого и запись переведённых файлов                       |
| **контекст**            | Чтение контекста проекта и организация | Управление контекстными группами, Glossary и пользовательскими промптами        |
| **Ресурсы организации** | Неприменимо                            | Загрузка и замена ресурсов, например шрифтов, общих для всех проектов организации |
| **runtime-перевод**     | Неприменимо                            | Перевод контента по запросу                                                       |
| **очередь перевода**    | Неприменимо                            | Постановка задач перевода файлов в очередь для фоновой обработки                  |
| **Настройки проекта**   | Неприменимо                            | Обновление настроек проекта, например локали по умолчанию и CDN delivery          |

Включите **Создание проекта** для автоматизации, вызывающей эндпоинт [Создание проекта](/docs/platform/openapi/reference/projects/create-project). Его разрешение `org:projects:create` также позволяет создавать проекты с включённой CDN delivery, а **Настройки проекта** (`project:write`) нужны только для последующего изменения настроек. Предоставляйте каждому ключу только необходимые ему разрешения.

Установите для **контекста** значение **Чтение** или **Write** для автоматизации, вызывающей [Context Management API](/docs/platform/openapi/reference/context-groups/list-context-groups) (`org:context:read` / `org:context:write`). Ключ организации с этим разрешением может работать с любой контекстной группой в организации. [Ключ проекта](#create-project-keys) имеет доступ только к группам, назначенным его проекту, и не может создавать, изменять, удалять группы, а также назначать их или отменять их назначение.

Установите для **Ресурсов организации** значение **Write** для автоматизации, которая загружает шрифты для перевода Lottie, например при синхронизации [`fonts`](/docs/cli/reference/config#fonts) через CLI (`org:assets:write`). Ключи проекта не могут загружать шрифты.

Установите для **Ключей API проекта** значение **Write** для автоматизации, вызывающей [Создание ключа API проекта](/docs/platform/openapi/reference/api-keys/create-project-api-key) или [Удаление ключа API проекта](/docs/platform/openapi/reference/api-keys/delete-project-api-key). Значения **Чтение** достаточно, чтобы [получить список](/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) укажите разрешения явно или не указывайте их вовсе — тогда будут предоставлены все разрешения проекта, которые вы можете делегировать. В отличие от элементов управления Dashboard, явно предоставленное через HTTP разрешение Write не включает Чтение.

## Создание ключей проекта [#create-project-keys]

Ключи проекта создаются в разделе **проект &gt; Ключи API**. Новые ключи начинаются с `gtx-api-` и работают в окружениях разработки, подготовки к проверке и рабочей среды. Их разрешения определяют, какие операции они могут выполнять.

1. Создайте ключ и укажите понятное **Name**.
2. В разделе **Разрешения** выберите **All** или **Custom**.
3. Для варианта **Custom** задайте уровень доступа, необходимый для каждого ресурса.
4. Нажмите **Create** и сразу скопируйте ключ целиком. Храните его в переменных окружения или в менеджере секретов.

Ключи проекта поддерживают следующие ресурсы:

| Ресурс                | Чтение                                     | Запись или включение                                                                                |
| --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| **Файлы**             | Чтение файлов проекта и переводов          | Загрузка исходного содержимого и запись переведённых файлов                                         |
| **контекст**          | Чтение контекстных групп, назначенных проекту | Генерация контекста, а также редактирование и изменение порядка контекстных групп, назначенных проекту |
| **runtime-перевод**   | Не применяется                             | Перевод содержимого по запросу                                                                      |
| **очередь перевода**  | Не применяется                             | Постановка задач перевода файлов в очередь                                                          |
| **настройки проекта** | Не применяется                             | Изменение настроек проекта                                                                          |

С разрешением **контекст** ключ проекта может обращаться к [Context Management API](/docs/platform/openapi/reference/context-groups/list-context-groups) для контекстных групп, назначенных его проекту. **Чтение** (`project:context:read`) позволяет получать список этих групп, а также читать и экспортировать их Glossary и пользовательские промпты. **Write** (`project:context:write`) дополнительно позволяет редактировать и импортировать это содержимое, менять порядок групп и генерировать контекст. Ключ проекта не может создавать, изменять, удалять, назначать контекстную группу или отменять её назначение — для этих действий нужен ключ организации. Для группы, не назначенной проекту ключа, возвращается тот же `403`, что и для несуществующей группы.

Для локального перевода по запросу подойдёт любой ключ проекта с разрешением `project:translations:generate`, в том числе ключ с полным доступом. Чтобы снизить риски, рекомендуем завести отдельный ключ с разрешениями **Custom**: для **runtime-перевода** выберите **Enabled**, а остальным ресурсам оставьте значение **None**. Для pipeline перевода файлов выдайте **Файлы &gt; Write** (включает и Чтение), **очередь перевода &gt; Enabled** и **контекст &gt; Write**. [`gt translate`](/docs/cli/reference/commands/translate) генерирует контекст перед постановкой переводов в очередь, поэтому без **контекст &gt; Write** команда завершится ошибкой. Если же вы создаёте ключ через 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`, поскольку в этом случае Write не включает Чтение.

Настройка SDK `devApiKey` и переменная окружения `GT_DEV_API_KEY` по-прежнему включают перевод в процессе разработки и горячую перезагрузку. Укажите в этой настройке ключ проекта с разрешением на runtime-перевод. Название настройки не означает, что требуется отдельный тип ключа.

В большинстве рабочих процессов 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]

Используйте понятные названия, чтобы ключи потом было легко находить.

Откройте список ключей в проекте или организация, чтобы просмотреть существующие ключи. В списке ключей отображаются:

* **Name** и **Key** — включая сокращённый ключ для удобного распознавания
* **разрешение** — как для ключей проекта, так и для ключей организация
* **Created** — дата создания ключа
* **Last Used** — когда ключ использовался в последний раз

При наличии разрешения на управление ключами используйте **Edit key**, чтобы переименовать ключ или изменить его разрешения, и **Delete**, чтобы отозвать его. Полный секрет отображается только в момент создания ключа.

Отзывайте ключи, которые больше не используются, и создавайте новые при ротации учётных данных. Удалённый ключ, как правило, перестаёт работать сразу, но в любом случае — не позднее чем через 10 минут.

Чтобы выполнить ротацию ключа проекта в рамках автоматизации, [создайте](/docs/platform/openapi/reference/api-keys/create-project-api-key) новый ключ, переключите на него свой рабочий процесс, а затем [удалите](/docs/platform/openapi/reference/api-keys/delete-project-api-key) старый ключ по его ID. Для обоих вызовов нужен ключ организации, у которого для **Ключей API проекта** задано значение **Write**.

## Существующие ключи разработки [#existing-keys]

Существующие ключи `gtx-dev-` по-прежнему проходят аутентификацию как ключи проекта. Ключи со старым разрешением по умолчанию (только runtime) теперь получают разрешения проекта по умолчанию, включая файлы, контекст, очередь перевода и настройки проекта. Остальные пользовательские наборы разрешений сохраняются.

Проверьте существующие ключи в разделе **Project &gt; API Keys**. Для локальной разработки рекомендуем ограничить их до **runtime-перевода** или заменить новыми ключами, работающими только в runtime. Ключи с полным доступом продолжают работать, но префикс `gtx-dev-` больше не означает ограниченные разрешения. Никогда не включайте такие ключи в клиентские бандлы, которые вы развёртываете.

## Рекомендации по безопасности [#security-practices]

* Никогда не коммитьте ключи в систему контроля версий.
* Никогда не включайте API-ключи в развёрнутые бандлы браузерных или мобильных приложений, независимо от их разрешений. Храните учётные данные развёрнутых приложений в серверных переменных окружения или в менеджере секретов.
* API-ключи можно использовать в клиентском коде, который отдаётся только вашим локальным сервером разработки. Проектные ключи с полным доступом тоже работают, но мы рекомендуем ограничивать локальные ключи разработки разрешением **Runtime-перевод** (`project:translations:generate`), чтобы минимизировать риски.
* Храните ключи в переменных окружения или в менеджере секретов.
* Используйте отдельные ключи для разработки, стейджинга и продакшена.
* Регулярно меняйте ключи.
* Отзывайте неиспользуемые ключи.
* Выбирайте минимально необходимую для интеграции область.

## Sitemap

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